@uncaged/cli

Developer CLI for Uncaged Agent — identity, data queries, and API debugging.

Quick Start

cd /path/to/uncaged

# Initialize config from wrangler.toml
npx @uncaged/cli init

# Login (uses SIGIL_DEPLOY_TOKEN from Infisical or env)
npx @uncaged/cli login --as scott

# Query D1 database
npx @uncaged/cli db users
npx @uncaged/cli db "SELECT id, slug FROM users LIMIT 5"

# API health check (RFC-004 route: /scott/api/v1/health)
npx @uncaged/cli api health

# Environment management
npx @uncaged/cli config env xiaoju
npx @uncaged/cli config show

Commands

uncaged init

Initialize .uncagedrc.json from packages/worker/wrangler.toml. Auto-detects environments from route patterns and D1 database config.

uncaged login [--as <slug>]

Authenticate and cache token to ~/.uncaged/auth.json (chmod 600). Reads SIGIL_DEPLOY_TOKEN from env or Infisical.

uncaged db <query|shortcut>

Query D1 database via wrangler d1 execute.

Shortcuts:

• db users — List all users
• db agents — List agents with owner info
• db channels — List channels (web, telegram, api)
• db tables — List all table names
• db schema — Show table DDL

Raw SQL:

uncaged db "SELECT id, slug FROM users WHERE slug LIKE 'scott%'"

uncaged api health

Health check using RFC-004 route format: /:user/api/v1/health

uncaged api call <METHOD> <path>

Raw API call with auth:

uncaged api call GET /scott/doudou/soul
uncaged api call POST /scott/doudou/chat --data '{"message":"hello"}'

uncaged config

View/manage configuration.

uncaged config              # Show current config
uncaged config show         # Same as above
uncaged config env xiaoju   # Switch environment
uncaged config set user bob # Change default user

uncaged auth (Phase 2)

Admin operations for user and agent management.

uncaged auth create-test-user --slug alice  # Create test user + agent
uncaged auth delete-test-user --slug alice  # Delete user + cascade
uncaged auth list-users                     # List all users
uncaged auth list-agents                    # List all agents

Configuration

.uncagedrc.json (project root)

{
  "currentEnv": "production",
  "environments": {
    "production": {
      "baseUrl": "https://uncaged.shazhou.work",
      "databaseId": "24bc6992-...",
      "databaseName": "uncaged-memory"
    }
  },
  "defaults": {
    "user": "scott",
    "channel": "web"
  }
}

~/.uncaged/auth.json (chmod 600)

JWT cache, isolated per environment.

Auth Token

The CLI needs SIGIL_DEPLOY_TOKEN for authentication. Resolution order:

1. UNCAGED_ADMIN_TOKEN env var
2. SIGIL_DEPLOY_TOKEN env var
3. secret get SIGIL_DEPLOY_TOKEN (Infisical)

Phase 1 Scope

• ✅ Config initialization from wrangler.toml
• ✅ JWT-based authentication with secure caching
• ✅ D1 queries (raw SQL + shortcuts)
• ✅ API health check (RFC-004 route format)
• ✅ Multi-environment support
• ✅ SQL injection protection (destructive query blocking)

Phase 2: Test User Lifecycle

• ✅ uncaged auth create-test-user --slug <slug> — One-step user + agent creation (1:1 per RFC-004)
• ✅ uncaged auth delete-test-user --slug <slug> — Full cascade delete (handles all FK deps)
• ✅ uncaged auth list-users — Show all users with agent count
• ✅ uncaged auth list-agents — Show all agents with owner info
• ✅ Admin token from Infisical (UNCAGED_ADMIN_TOKEN) with fallback to SIGIL_DEPLOY_TOKEN
• ✅ Friendly error handling (slug validation, duplicate detection, FK-aware deletion)

Usage

# Create a test user (creates user + agent + agent_users binding)
uncaged auth create-test-user --slug alice

# Login as the test user
uncaged login --as alice
uncaged api health

# List all users and agents
uncaged auth list-users
uncaged auth list-agents

# Delete test user (cascade: messages, tokens, channels, bindings, agents, user)
uncaged auth delete-test-user --slug alice

Related

• RFC: #131 (uncaged-cli)
• Testing Phase 1: #138
• Testing Phase 2: #139
• Depends on: RFC-004 Phase 0+1 (#132, #133)