Studio CLI Commands¶

Experimental development surface

This analysis, provider or Studio surface is outside the stable backend contract. Review its outputs and application integration before use. It is not required for REST, synchronous MCP or Durable Operations. See stability labels.

Command-line tools for testing and managing Aksara Studio integration.

Commands Overview¶

Command	Description
`aksara studio handshake`	Test handshake locally
`aksara studio url`	Show Studio endpoint URLs

aksara studio handshake¶

Test the Studio handshake locally without starting a server.

Usage¶

aksara studio handshake [OPTIONS]

Options¶

Option	Default	Description
`--app, -a`	`main:app`	App path (module:variable)
`--format, -f`	`pretty`	Output format: `json` or `pretty`

Examples¶

# Test with default app (main:app)
aksara studio handshake

# Test with custom app path
aksara studio handshake --app myapp:application

# Output as JSON for scripting
aksara studio handshake --format json

# Pipe to jq for processing
aksara studio handshake --format json | jq '.checksums'

Sample Output (pretty)¶

  ⚡ Aksara Studio - Handshake Test

  ✓ Handshake successful!

  Project:
    Name:           My API
    Version:        1.0.0
    Aksara:         0.7.2
    Python:         3.11.5
    Environment:    development
    Debug:          True

  Database:
    Connected:      True
    Pool Size:      10
    Available:      8

  Capabilities:
    • read_schema
    • read_data
    • ai_tools
    • admin_access
    • debug_panels

  Checksums:
    Schema:         abc123def456789
    Migrations:     def456abc123789
    Settings:       789abc123def456
    Routes:         123def456abc789

Sample Output (json)¶

{
  "protocol_version": "1.0",
  "timestamp": "2024-01-15T10:30:00Z",
  "project": {
    "name": "My API",
    "version": "1.0.0",
    "aksara_version": "0.7.2",
    "python_version": "3.11.5",
    "debug_mode": true,
    "environment": "development"
  },
  "database": {
    "connected": true,
    "dialect": "postgresql",
    "pool_size": 10,
    "pool_available": 8,
    "latency_ms": null,
    "last_error": null
  },
  "capabilities": [
    "read_schema",
    "read_data",
    "ai_tools",
    "admin_access",
    "debug_panels"
  ],
  "checksums": {
    "schema_checksum": "abc123def456789",
    "migrations_checksum": "def456abc123789",
    "settings_checksum": "789abc123def456",
    "routes_checksum": "123def456abc789"
  },
  "endpoints": {
    "context_full": "/ai/context/full",
    "context_summary": "/studio/context/summary",
    "health": "/studio/health",
    "tools": "/ai/tools",
    "tools_mcp": "/ai/tools/mcp",
    "query_execute": "/ai/query/execute",
    "codegen_preview": "/ai/codegen/preview",
    "patch_preview": "/ai/patch/preview",
    "patch_apply": "/ai/patch/apply",
    "plan_preview": "/ai/plan/preview",
    "plan_apply": "/ai/plan/apply",
    "schema_health": "/ai/schema/health"
  },
  "metadata": {}
}

aksara studio url¶

Display the URLs for Studio integration endpoints.

The command only formats URLs; it does not verify that Studio is mounted, authenticated, or reachable. See configuration before opening or calling an enabled Studio surface.

Usage¶

aksara studio url [OPTIONS]

Options¶

Option	Default	Description
`--host, -h`	`localhost`	Server host
`--port, -p`	`8000`	Server port
`--https/--no-https`	`--no-https`	Use HTTPS

Examples¶

# Show URLs for default localhost:8000
aksara studio url

# Custom port
aksara studio url --port 8080

# HTTPS URLs
aksara studio url --https

# Custom host and port
aksara studio url --host api.myapp.com --port 443 --https

Sample Output¶

  ⚡ Aksara Studio - Endpoint URLs

  Studio Endpoints:
    Handshake:       http://localhost:8000/studio/handshake
    Context Summary: http://localhost:8000/studio/context/summary
    Health:          http://localhost:8000/studio/health

  AI Endpoints (full context):
    Full Context:    http://localhost:8000/ai/context/full
    Tools:           http://localhost:8000/ai/tools
    Tool Catalog:    http://localhost:8000/ai/tools/mcp
    MCP Protocol:    http://localhost:8000/mcp/ (when enabled)

  Tip: Use --https for production URLs

Troubleshooting¶

"Failed to load app"¶

✗ Failed to load app 'main:app': No module named 'main'

Solution: Make sure you're in your project directory and the app path is correct:

cd /path/to/your/project
aksara studio handshake --app myapp:app

"Handshake failed"¶

If handshake fails, check:

Import errors - Your models may have import issues
Configuration errors - Check your Settings configuration
Database issues - Database URL may be invalid

Use --format json to see the full error:

aksara studio handshake --format json 2>&1

Database Shows "Not Connected"¶

This is normal - the CLI handshake doesn't start the database connection pool. Use the HTTP endpoint for full database status:

# Start your app
aksara dev

# Test via HTTP
curl http://localhost:8000/studio/health | jq