CLI Usage

Complete reference guide for all Gears CLI commands.

Working with AI Agents

Important: When using Gears with AI coding agents (like Claude, Cursor, or GitHub Copilot), always ask the agent to run Gears commands directly in the terminal rather than just discussing them.

The command output teaches the agent about:

• Your workspace structure and file organization
• Available documentation and current project state
• Command options and proper usage patterns

Example:

• ❌ "Tell me about my stories"
• ✅ "Run gears story list and explain what you see"

This approach helps the agent learn your system and provide more accurate assistance.

Global Flags

All commands support these global flags:

• --help, -h - Show help for any command
• --version, -v - Show version information

Commands

gears init

Initialize a new .gears directory in your project.

gears init

Creates the directory structure:

• sessions/ - Daily session logs
• story/ - Feature stories
• adr/ - Architecture Decision Records
• memory/ - Project knowledge
• context/ - Current work context

gears auth

Authenticate with Gears and generate an API token.

gears auth

Opens your browser to log in or register. Saves the token locally for future commands.

Options:

• logout - Logout and remove stored token

Example:

gears auth logout

gears hydrate

Generate deterministic onboarding/hydration output for agent sessions.

gears hydrate

Common flags:

• --chat - startup inbox-style directive check
• --quick - concise checklist
• --full - full checklist (default)

gears session

Create or open today's session file.

gears session

Creates .gears/sessions/YYYY-MM-DD.md if it doesn't exist.

gears story

Manage feature stories and specifications.

Create New Story

gears story new "feature name"

Creates .gears/story/story-feature-name.md with a template.

List Stories

gears story list

Shows all stories organized by status.

gears adr

Manage Architecture Decision Records.

Create New ADR

gears adr new "decision title"

Creates a new ADR file with sequential numbering.

List ADRs

gears adr list

Shows all ADRs with their status.

gears sync

Synchronize .gears files with Gears.

Push Files

gears sync push

Uploads all .gears files to the cloud. Only uploads files that have changed.

Options:

• --force - Upload all files regardless of changes

Pull Files

gears sync pull

Downloads files from Gears to your local .gears directory.

Options:

• --force - Overwrite local files without prompting

gears completion

Generate shell completion scripts.

# Bash
gears completion bash > /etc/bash_completion.d/gears

# Zsh
gears completion zsh > /usr/local/share/zsh/site-functions/_gears

# PowerShell
gears completion powershell | Out-String | Invoke-Expression

Additional Top-Level Commands

The CLI also includes these workspace operations:

• gears events - View/manage workspace events
• gears inbox - Read/manage inbox directives
• gears log - Command/activity history
• gears projects - List workspace projects
• gears sessions - List/inspect session docs
• gears status - Workspace status overview
• gears watch - Workspace monitoring control
• gears workspace - Desktop workspace registry actions

Configuration File

Configuration is stored in:

• Workspace-local: .gears/.gearbox/config.json

Example configuration:

{
    "workspace_id": "ws_...",
    "api_base_url": "https://...",
    "api_token": "..."
}

Exit Codes

• 0 - Success
• 1 - General error
• 2 - Authentication error
• 3 - Network error
• 4 - File not found

Examples

Complete Workflow

# Initialize project
cd ~/my-project
gears init

# Authenticate
gears auth

# Create session
gears session

# Create a story
gears story new "user authentication"

# Push to cloud
gears sync push

Daily Routine

# Start of day: create session and pull latest
gears session
gears sync pull

# End of day: push your work
gears sync push

Next Steps

• Learn about file synchronization
• Explore the API