CLI

npm install -g @aura-work/cli

npx @aura-work/cli status

📋 Complete Command Reference

Command	Description	Example
aura status	Check bridge health and connection	aura status
aura pair --code <code>	Pair CLI with desktop app	aura pair --code ABC123
aura projects	List all projects	aura projects
aura task create	Create and start a task	aura task create --project my-app --prompt "Add auth"
aura task get <id>	Get task details and status	aura task get task_abc123
aura task logs <id>	Stream task execution logs	aura task logs task_abc123
aura open task <id>	Open task in desktop UI	aura open task task_abc123

🔐 Pairing Flow

The CLI connects to the desktop app through the Bridge sidecar. Here's how to set it up:

1. 1. Open the desktop app and go to Extensions → Pair New Device
2. 2. A pairing code is displayed (valid for 10 minutes)
3. 3. Run aura pair --code <code> in your terminal
4. 4. The CLI saves a session token to ~/.aura/config.json
5. 5. All subsequent commands use this token for authentication

The pairing creates a secure session. You can revoke access anytime from the desktop app under Extensions → Paired Devices.

🔄 Usage Examples

Create a task from the terminal

# Create a task in the current project
aura task create --prompt "Fix the login bug in auth.ts"

# Create a task in a specific project
aura task create --project my-web-app --prompt "Add user profile page"

# Create a task with specific permissions
aura task create --prompt "Refactor database" --permissions "file,shell"

Monitor task progress

# Get task status
aura task get task_abc123

# Stream logs in real-time
aura task logs task_abc123

# Open task in desktop UI for visual monitoring
aura open task task_abc123

Automation script

#!/bin/bash
# Run a task and wait for completion
TASK_ID=$(aura task create --prompt "Run tests" --json | jq -r '.id')
echo "Task created: $TASK_ID"

# Poll for completion
while true; do
  STATUS=$(aura task get $TASK_ID --json | jq -r '.status')
  if [ "$STATUS" = "completed" ]; then
    echo "Task completed!"
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Task failed!"
    exit 1
  fi
  sleep 5
done

🔒 Security Model

The CLI connects through the local Bridge sidecar (port 47826). Key security features:

• Session-based auth — each CLI session has a unique token
• Permission respect — CLI cannot bypass any permission, it follows the same profiles as the desktop UI
• Local only — Bridge only listens on localhost, no remote access
• Token revocation — revoke CLI access anytime from the desktop app
• Audit logging — all CLI actions are logged in the audit trail

The Bridge sidecar runs only when the desktop app is open. It stops when the app closes — no background daemon.

⚡ CI/CD Integration

Use the CLI in automation pipelines:

# GitHub Actions example
name: Run AI Task
on: push
jobs:
  ai-task:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm install -g @aura-work/cli
      - run: aura pair --code ${{ secrets.AURA_PAIR_CODE }}
      - run: aura task create --prompt "Review code changes" --wait

Store the pairing code as a GitHub secret. The --wait flag blocks until the task completes.

🛠️ Configuration

The CLI stores its configuration in ~/.aura/config.json:

{
  "sessionToken": "abc123...",
  "bridgeHost": "localhost",
  "bridgePort": 47826,
  "defaultProject": "my-project",
  "outputFormat": "text"  // or "json"
}

Set outputFormat to json for machine-readable output in scripts.