Command: gears auth

Authenticate with the mygears.dev platform to enable cloud synchronization.

Overview

The auth command connects your local Gears CLI to your mygears.dev account, allowing you to sync your .gears documentation across projects and machines. It opens your browser for authentication and securely stores your API token locally.

Syntax

run gears auth           # Authenticate and save token
run gears auth logout    # Remove stored token

Subcommands

`gears auth`

Initiates the authentication flow to connect to mygears.dev.

Process:

Opens your browser to the mygears.dev authentication page
Login or register if you haven't already
Copy the generated API token
Paste the token into your terminal when prompted
Token is validated and stored in .gears/config.json

`gears auth logout`

Removes your stored authentication token and disconnects from mygears.dev.

run gears auth logout

Working with AI Agents

Have your AI agent run authentication commands to understand the auth flow.

gears auth - Agent sees the authentication process and token validation
gears auth logout - Agent learns about token management and security

The output teaches the agent:

How authentication works with mygears.dev
Where tokens are stored (.gears/config.json)
That tokens are never committed to git (gitignored by default)

This helps the agent understand your security setup and avoid exposing credentials.

Examples

First-Time Authentication

$ run gears auth
Authenticate with the gears-hub API

Opening browser for authentication...
Waiting for token...

Please visit: https://mygears.dev/tokens
Create a token and paste it here:

Token: ••••••••••••••••••••••••••••••••

✓ Token validated
✓ Saved to .gears/config.json
User: john.doe@example.com

[OK] Authenticated

Re-authenticating

If your token expires or you want to switch accounts:

# Logout first
$ run gears auth logout
✓ Token removed

# Authenticate with new account
$ run gears auth
Opening browser for authentication...
[authentication flow continues]

Logout

$ gears auth logout
Removing authentication token...
✓ Token removed from .gears/config.json

You can re-authenticate anytime with 'gears auth'

Token Storage

Your API token is stored locally in .gears/config.json:

{
    "api_url": "https://mygears.dev",
    "token": "your-token-here",
    "user_email": "you@example.com"
}

Security Notes:

The token file is stored locally only
Add .gears/config.json to your .gitignore to avoid committing tokens
Never share your token or commit it to version control
Tokens can be revoked at any time from the mygears.dev dashboard

Required Token Abilities

When creating a token at mygears.dev, ensure it has these abilities:

files:read - Read your synced files
files:write - Upload and update files

These abilities are required for gears sync push and gears sync pull commands to work.

Common Workflows

Initial Setup on New Machine

# 1. Clone your project (with .gears directory)
git clone <your-repo>
cd your-project

# 2. Authenticate with your account
gears auth

# 3. Pull latest documentation from cloud
gears sync pull

Switching Accounts

# 1. Logout from current account
gears auth logout

# 2. Authenticate with different account
gears auth

# 3. Sync with new account's files
gears sync pull --force  # Overwrites local files

Team Collaboration

Each team member:

# 1. Has their own mygears.dev account
# 2. Authenticates individually
gears auth

# 3. All sync to the same project namespace
gears sync push  # Everyone's updates merge

Troubleshooting

Browser Doesn't Open

Problem: Browser doesn't launch when running gears auth

Solution: Manually visit the authentication URL:

$ gears auth
Opening browser for authentication...
(If browser doesn't open, visit: https://mygears.dev/tokens)

Navigate to https://mygears.dev/tokens in your browser manually.

Invalid Token Error

Problem: Token validation fails

Error: Invalid token or insufficient permissions

Solutions:

Check token abilities: Ensure your token has files:read and files:write abilities at https://mygears.dev/tokens
Create new token: Generate a fresh token from the dashboard
Check internet connection: Ensure you can reach mygears.dev
Token expired: Some tokens may have expiration dates - create a new one

Network Connection Error

Problem: Cannot connect to mygears.dev

Error: Could not connect to gears-hub API
Check your internet connection

Solutions:

Verify internet connectivity
Check if mygears.dev is accessible: curl https://mygears.dev
Check firewall settings
Try again after a moment (may be temporary network issue)

Token File Not Found

Problem: Running gears sync commands says "not authenticated"

Error: Not authenticated. Run 'gears auth' first

Solution: Your token may have been deleted or corrupted:

# Check if config file exists
ls .gears/config.json

# If missing or corrupted, re-authenticate
gears auth

Security Best Practices

Never commit tokens: Add .gears/config.json to .gitignore
```
echo ".gears/config.json" >> .gitignore
```
Use token management: Regularly review and revoke unused tokens at https://mygears.dev/tokens
One token per machine: Create separate tokens for different development environments (work laptop, home PC, etc.)
Rotate tokens: Periodically create new tokens and revoke old ones
Revoke on compromise: If your token is exposed, immediately revoke it from the dashboard

Token Management Dashboard

Visit https://mygears.dev/tokens to:

View all your active tokens
See when each token was created and last used
Revoke tokens you no longer need
Create new tokens with specific abilities
Monitor token usage and activity

Related Commands

gears init - Initialize .gears directory structure
gears sync push - Upload files (requires auth)
gears sync pull - Download files (requires auth)

Next Steps

After authenticating:

Verify connection: Run gears sync push to test the connection
Pull existing docs: Run gears sync pull if joining an existing project
Start syncing: Your files will now sync to mygears.dev automatically

← Command: init | Command: session →