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.

run 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.

run 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:

run gears auth --logout

gears session

Create or open today's session file.

run gears session

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

gears story

Manage feature stories and specifications.

Create New Story

run gears story new "feature name"

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

List Stories

run gears story list

Shows all stories organized by status.

gears adr

Manage Architecture Decision Records.

Create New ADR

run gears adr new "decision title"

Creates a new ADR file with sequential numbering.

List ADRs

run 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

Configuration File

Configuration is stored in:

  • Windows: %APPDATA%\.gears\config.json
  • macOS/Linux: ~/.gears/config.json

Example configuration:

{
    "api_url": "https://mygears.dev/api",
    "token": "your-api-token-here"
}

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

← Back to Documentation Home
Last updated: Mar 27, 2026