Getting Started

This guide will help you get up and running with Gears in just a few minutes.

Prerequisites

Go 1.21 or later (for CLI installation)
A Gears account
A workspace with /root/projects/{your-git-repo} structure

Important: Workspace Structure

Gears uses a specific workspace structure:

/root/                          # Your workspace root (run gears init HERE)
├── .gears/                     # Shared directory for ALL projects
│   ├── sessions/
│   ├── story/
│   ├── adr/
│   └── config.json
└── projects/                   # All your project repositories
    ├── my-api/                 # Git repository 1
    ├── my-frontend/            # Git repository 2
    └── my-mobile/              # Git repository 3

Critical: Run gears init from /root (your workspace root), NOT from inside a project directory. The .gears directory manages documentation for ALL your projects from one location.

Step 1: Install the CLI

Install the gears command-line tool using Go:

go install github.com/Syluxso/gears@latest

Verify the installation:

gears version

Step 2: Initialize Your Workspace

Navigate to your workspace root (NOT a project directory) and run the init command:

cd /root  # Your workspace root where /root/projects/ exists
run gears init

💡 Pro Tip for AI Agents: Always ask your AI agent to run gears init for you. The command output teaches the agent about the directory structure and what each folder is for.

This creates the .gears directory structure at root level:

.gears/
├── sessions/     # Daily AI conversation logs
├── story/        # Feature specifications
├── adr/          # Architecture decisions
├── memory/       # Project knowledge base
└── context/      # Current work tracking

Step 3: Authenticate with Gears

Run the auth command to connect your local CLI to Gears:

run gears auth

💡 Pro Tip for AI Agents: Have your AI agent run gears auth and walk you through the process. The agent will see the authentication flow and understand how tokens work.

This will:

Open your browser to the authentication page
Allow you to log in or register
Generate an API token
Save the token locally for future commands

Step 4: Create Your First Session

Run the session command to create today's session file:

run gears session

💡 Pro Tip for AI Agents: Ask your agent to run gears session at the start of each work session. The command output reminds the agent what session files are for and how they track daily work.

This creates a markdown file at .gears/sessions/YYYY-MM-DD.md where you can log your work.

Step 5: Push Files to Cloud

Run the sync push command to upload your .gears files:

run gears sync push

💡 Pro Tip for AI Agents: Always have your AI agent run gears sync push and gears sync pull. The output shows what files are being synced and teaches the agent about the synchronization system.

Your files are now backed up and accessible from the web dashboard at Gears.

Next Steps

Learn about CLI commands
Understand file synchronization
Explore the API