Skip to main content

CLI Reference

The Styrby CLI runs on your development machine, detects active AI agents, and streams session data to the dashboard.

System Requirements

  • Node.js 20 or later
  • macOS, Linux, or WSL2 on Windows
  • Outbound HTTPS (port 443) to styrbyapp.com and supabase.co

Installation

npm install -g styrby-cli

# Or with your preferred package manager
pnpm add -g styrby-cli
yarn global add styrby-cli

Commands

styrby onboard

Interactive setup wizard. Handles GitHub OAuth authentication, machine registration, and mobile QR code pairing. Run this once on a new machine.

styrby onboard
# --skip-pairing    Skip the mobile QR code step
# --force           Re-authenticate even if already logged in

styrby pair

Generates a new QR code for pairing a mobile device. Use this when you get a new phone or want to add another device after initial setup. Requires prior authentication via styrby onboard.

styrby pair
# Scan the QR code with the Styrby mobile app
# Waiting for mobile app to connect...

styrby start

Starts a session with a specific agent. Agent shorthands are also supported as a faster alternative.

styrby start --agent claude
styrby start --agent codex

# All 11 agents have a shorthand. Each is equivalent to "styrby start --agent <name>":
styrby claude     styrby goose      styrby kilo
styrby codex      styrby amp        styrby kiro
styrby gemini     styrby crush      styrby droid
styrby opencode   styrby aider

# Bare command uses your default agent (configurable via ~/.styrby/config.json)
styrby

# Common flags
#   -a, --agent <name>     Agent to use (overrides shorthand and config)
#   -p, --project <path>   Project directory (default: cwd)

styrby status

Shows the current state of the CLI: pairing status, detected agents, active sessions, and connection health.

styrby status
# Machine: paired (abc123)
# Agents:  2 active (claude, codex)
# Session: ses_8f3k2... (running, 4,218 tokens)
# Session: ses_9g4m1... (idle, 890 tokens)

styrby stop

Stops the running Styrby daemon process.

styrby doctor

Runs health checks: Node.js version, configuration file, authentication status, and installed agent detection. Use this to diagnose problems.

styrby doctor
#   ✓ [PASS] Node.js version: 20.x.x (>= 20 required)
#   ✓ [PASS] Configuration: Config file loaded successfully
#   ✓ [PASS] Authentication: Authenticated
#   ✓ [PASS] AI Agents: 2 agent(s) found: Claude Code, Codex

styrby install

Installs an AI coding agent via npm. Supported agents: claude, codex, gemini, opencode.

styrby install claude
styrby install codex
styrby install gemini
styrby install opencode
styrby install --all    # Install all agents

styrby costs

Displays token usage and cost data for recent sessions.

styrby logs

View daemon logs.

styrby logs
styrby logs --follow    # Stream logs in real time

styrby upgrade

Checks for and installs CLI updates from npm.

styrby upgrade           # Check and install update
styrby upgrade --check   # Check only, do not install

styrby daemon

Manages CLI auto-start on boot. On macOS uses a LaunchAgent plist; on Linux uses a systemd user service.

styrby daemon install    # Set up auto-start on login
styrby daemon uninstall  # Remove auto-start
styrby daemon status     # Check auto-start status

styrby template

Manage reusable prompt templates.

styrby template list                   # List all your templates
styrby template create <name>          # Create interactively
styrby template show <name>            # Show template content
styrby template use <name>             # Render with variable substitution
styrby template delete <name>          # Delete (with confirmation)

styrby resume

Re-attach the relay to an existing session without spawning a new agent process. Useful after a network blip or daemon restart.

styrby resume                          # Re-attach to most recent live session
styrby resume <sessionId>              # Re-attach to a specific session

styrby auth

Re-authenticate with GitHub without re-running the rest of the onboarding wizard. Use --force to invalidate the existing token first.

styrby checkpoint

Save and restore named positions inside a session timeline. Aliased as styrby cp.

styrby checkpoint save <name>          # Save current position as named checkpoint
styrby checkpoint list                 # List checkpoints for current session
styrby checkpoint restore <name>       # Show restore info for a checkpoint
styrby checkpoint delete <name>        # Delete a checkpoint (--force to skip prompt)

styrby export / styrby import

Move sessions between machines or archive them as JSON files.

styrby export <sessionId>              # Print JSON to stdout
styrby export <sessionId> --output session.json
styrby export --all --output ./backup  # Export every session to a directory
styrby import session.json             # Import a single session JSON

styrby privacy

GDPR data subject rights from the terminal. Subject access (Art. 15 / 20) exports every row tied to your account. Erasure (Art. 17) hard-deletes the account behind a two-step confirmation.

styrby privacy export                  # Subject access request (SAR)
styrby privacy delete                  # Erase account (irreversible)
styrby export-data                     # Alias for "privacy export"
styrby delete-account                  # Alias for "privacy delete"

styrby mcp

Run the Styrby Model Context Protocol server so any MCP-aware agent (Claude Code, Goose, custom clients) can call into your active sessions.

styrby context

Inspect, sync, and copy the cross-agent context memory shared inside a session group. Useful when handing off work from one agent to another.

styrby context show   --group <groupId>
styrby context sync   --group <groupId>
styrby context export --session <sessionId>
styrby context import --session <target> --from <source>

Environment Variables

VariableDefaultDescription
STYRBY_API_URLhttps://api.styrbyapp.comAPI base URL. Override for staging.
STYRBY_LOG_LEVELinfoLogging verbosity: debug, info, warn, error.
STYRBY_ENVproductionSet to development to use local Supabase.
SUPABASE_URL(built-in)Override Supabase project URL (dev/self-hosted).
SUPABASE_ANON_KEY(built-in)Override Supabase anon key (dev/self-hosted).
ANTHROPIC_API_KEY(none)Required by Claude Code.
OPENAI_API_KEY(none)Required by Codex; optional for OpenCode.
GEMINI_API_KEY / GOOGLE_API_KEY(none)Required by Gemini CLI. Either name is accepted.

Provider keys are read directly by each agent process at session start. Styrby never reads or transmits them. See the Agent Setup page for per-agent authentication details.

Config is stored in ~/.styrby/config.json. The Supabase URL and anon key are embedded in the CLI binary and require no setup for the default (hosted) Styrby service.

Agent Detection

The CLI monitors the local process list for known agent binaries. When it detects one, it hooks into the agent's stdio streams to capture session data. No agent modification required.

Eleven agent binaries are recognised: claude, codex, gemini, opencode, aider, goose, amp, crush, kilo, kiro, droid. See the Agent Setup page for install commands and per-agent config paths. Run styrby doctor to see which are installed on this machine.

Getting StartedAgent Setup