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/cli

Or use it directly with npx:

npx @guidemode/cli --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.

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