CLI Reference

The GuideMode CLI provides command-line access to GuideMode features, including authentication, session validation, and work item management.

Installation

Install the CLI globally via npm:

npm install -g guidemode

Or use it directly with npx:

npx guidemode --help

Authentication

Before using work item commands, you must authenticate with your GuideMode server.

Login

guidemode login [--server <url>]

Opens a browser window for OAuth authentication. Once complete, your API key is stored locally.

Options:

• --server <url> - Server URL (default: https://app.guidemode.dev)

Example:

# Login to default server
guidemode login

# Login to custom server
guidemode login --server https://your-instance.guidemode.dev

Logout

guidemode logout

Removes stored credentials from your local machine.

Who Am I

guidemode whoami

Shows the current authenticated user and server.

Setup and Session Syncing

Setup

guidemode setup [--force] [--project] [--no-skill] [--default-policy <allow|deny>]

Logs you in, installs the Claude Code sync hooks, asks which repositories should sync, installs a skill that lets Claude manage syncing, and runs a health check.

Hooks are installed for your user account (~/.claude/settings.json) so they apply to every repository. Use --project to scope them to the current repository instead (.claude/settings.local.json).

Options:

• --force - Re-authenticate even if already logged in
• --project - Install hooks for this project only
• --no-skill - Skip installing the Claude Code skill
• --default-policy <allow|deny> - Choose the sync policy without being prompted

Choosing the default policy

Setup asks which repositories should sync and stores the answer. Because that choice decides what leaves your machine, it is never assumed: running setup without a terminal and without --default-policy stops with an explanation rather than picking one for you.

• allow - every repository syncs unless you disable it
• deny - nothing syncs until you enable it, repository by repository

Controlling which repositories sync

Because hooks are global, syncing is controlled per repository in configuration rather than by where the hooks live.

guidemode config                        # show settings and whether this repo syncs
guidemode disable [--note <text>]       # stop syncing this repository
guidemode enable                        # sync this repository again
guidemode disable --global              # stop syncing everywhere
guidemode enable --global               # resume
guidemode config --default-policy deny  # switch to opt-in mode later
guidemode config --refresh-cache        # forget cached repository lookups

Repositories are identified by their normalised git remote (for example github.com/acme/app), so all clones and worktrees of a repository share one setting. Directories with no remote are identified by path.

Status

guidemode status [--verbose] [--json]

Checks dependencies, credentials, server reachability, whether the hooks are actually present in your settings file, whether the current directory would sync, and recent log errors.

Sync

guidemode sync [--foreground]

Invoked by the Claude Code hooks. It performs only cheap checks and hands the upload to a detached background process, so it returns immediately rather than making you wait mid-session. Pass --foreground to upload inline when debugging.

Logs

guidemode logs [--lines <n>] [--errors] [--follow]

Background uploads report their results here.

Uninstall

guidemode uninstall [--purge]

Removes GuideMode’s hooks (leaving any other tools’ hooks intact) and the skill. --purge also clears local sync settings and cached state. Credentials are untouched; use guidemode logout for those.

Environment Variables

For CI/CD environments, you can use environment variables instead of interactive login:

export GUIDEMODE_API_KEY=gai_your_api_key_here
export GUIDEMODE_SERVICE_URL=https://app.guidemode.dev

Work Item Commands

Issue

Create or update an issue in GuideMode using GuideMode’s internal data model.

guidemode issue <title> --type <type> --state <state> --project <key> [options]

Required Arguments:

• <title> - Issue title

Required Options:

• --type <type> - Issue type: feature, bug, chore, discovery, incident, other
• --state <state> - Issue state: open, closed, in_progress
• --project <key> - Project key (e.g., "owner/repo" or custom identifier)

Optional:

• --external-id <id> - Unique external ID (auto-generated if omitted)
• --body <text> - Issue description
• --url <url> - Link to source issue
• --labels <labels> - Comma-separated labels
• --assignee <username> - Assignee username
• --closed-at <timestamp> - ISO8601 timestamp when closed
• --json - Output JSON response

Examples:

# Create a bug issue
guidemode issue "Fix login button" \
  --type bug \
  --state open \
  --project "myorg/myrepo"

# Create a feature with all options
guidemode issue "Add dark mode" \
  --type feature \
  --state in_progress \
  --project "myorg/myrepo" \
  --external-id "JIRA-123" \
  --body "Implement dark mode toggle in settings" \
  --labels "enhancement,ui" \
  --assignee "developer1"

# Close an existing issue
guidemode issue "Fix login button" \
  --type bug \
  --state closed \
  --project "myorg/myrepo" \
  --external-id "JIRA-123" \
  --closed-at "2024-01-15T10:00:00Z"

# Output JSON for scripting
guidemode issue "New feature" \
  --type feature \
  --state open \
  --project "myorg/myrepo" \
  --json

Deploy

Create or update a deployment in GuideMode.

guidemode deploy <ref> <sha> --env <environment> --status <status> --project <key> [options]

Required Arguments:

• <ref> - Branch, tag, or ref being deployed (e.g., main, v1.2.3)
• <sha> - Commit SHA (7-40 characters, short or full SHA)

Required Options:

• --env <environment> - Environment: production, staging, development, qa, preview, other
• --status <status> - Deployment status: pending, queued, in_progress, success, failure, error
• --project <key> - Project key (e.g., "owner/repo")

Optional:

• --external-id <id> - Unique external ID (auto-generated if omitted)
• --description <text> - Deployment description
• --url <url> - Deployment URL
• --rollback - Flag this as a rollback deployment
• --rollback-from <sha> - SHA being rolled back from (7-40 characters)
• --json - Output JSON response

Examples:

# Record a successful production deployment
guidemode deploy "main" "abc123def456789012345678901234567890abcd" \
  --env production \
  --status success \
  --project "myorg/myrepo"

# Record a deployment in progress
guidemode deploy "feature/new-ui" "abc123def456789012345678901234567890abcd" \
  --env staging \
  --status in_progress \
  --project "myorg/myrepo" \
  --description "Testing new UI components"

# Record a rollback
guidemode deploy "main" "abc123def456789012345678901234567890abcd" \
  --env production \
  --status success \
  --project "myorg/myrepo" \
  --rollback \
  --rollback-from "def456789012345678901234567890abcdef12"

# Output JSON for scripting
guidemode deploy "main" "abc123def456789012345678901234567890abcd" \
  --env production \
  --status success \
  --project "myorg/myrepo" \
  --json

CI/CD Integration

GitHub Actions

name: Track Deployment

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy application
        run: ./deploy.sh

      - name: Record deployment
        env:
          GUIDEMODE_API_KEY: ${{ secrets.GUIDEMODE_API_KEY }}
        run: |
          npx @guidemode/cli deploy "${{ github.ref_name }}" "${{ github.sha }}" \
            --env production \
            --status success \
            --project "${{ github.repository }}"

GitLab CI

deploy:
  stage: deploy
  script:
    - ./deploy.sh
    - |
      npx @guidemode/cli deploy "$CI_COMMIT_REF_NAME" "$CI_COMMIT_SHA" \
        --env production \
        --status success \
        --project "$CI_PROJECT_PATH"
  variables:
    GUIDEMODE_API_KEY: $GUIDEMODE_API_KEY

Shell Script

#!/bin/bash
# deploy.sh - Record deployment to GuideMode

set -e

# Get current git info
REF=$(git rev-parse --abbrev-ref HEAD)
SHA=$(git rev-parse HEAD)
PROJECT=$(git remote get-url origin | sed 's/.*github.com[:/]\(.*\)\.git/\1/')

# Deploy your application
echo "Deploying $REF ($SHA)..."
./actual-deploy-script.sh

# Record to GuideMode
guidemode deploy "$REF" "$SHA" \
  --env production \
  --status success \
  --project "$PROJECT" \
  --description "Automated deployment from CI"

Validation Command

Validate canonical JSONL session files.

guidemode validate <path> [options]

Arguments:

• <path> - Path to JSONL file or directory

Options:

• --strict - Treat warnings as errors
• --json - Output JSON format
• --verbose - Show detailed error information
• --watch - Watch for file changes and re-validate
• --provider <name> - Filter by provider name

Exit Codes

• 0 - Success
• 1 - Error (authentication, validation, or API error)

Configuration

Configuration is stored in ~/.guidemode/config.json:

{
  "apiKey": "gai_...",
  "serverUrl": "https://app.guidemode.dev",
  "username": "your-username",
  "tenantId": "...",
  "tenantName": "Your Organization"
}

The file is created automatically during login. Credentials are stored with restricted permissions (0600).