AlphaSwarm CLI Operator Guide

The AlphaSwarm CLI (alphaswarm-cli or alphaswarm) is the primary tool for operators and developers to interact with the AlphaSwarm platform.

Read the AlphaSwarm CLI README for installation instructions.

Command Map

alphaswarm-cli setup         init | verify | render-config
alphaswarm-cli services      list | status <service>
alphaswarm-cli update        check | apply [--dry-run]
alphaswarm-cli self-update   check | apply
alphaswarm-cli auth          login | whoami | authorize | providers | refresh | logout | elevate | scopes | assume | diagnose | status | keys * | device * | yubikey * | sessions *
alphaswarm-cli context       list | use | show | clear
alphaswarm-cli account       profile | update | change-password | delete | audit | sessions * | mfa * | connections *
alphaswarm-cli roles         list | show | assign | revoke | bindings | holders | whoami | can | explain | grant-scope
alphaswarm-cli domains       tree | bind | unbind | members | migrate-strategy
alphaswarm-cli admin         whoami | health
alphaswarm-cli orgs          list | show | create | update | delete | teams | workspaces | members * | settings *
alphaswarm-cli users         list | show | create | update | invite | deactivate | activate | delete | memberships *
alphaswarm-cli teams         list | create | show | update | delete | members | add-member | remove-member
alphaswarm-cli projects      list | create | show | update | archive | unarchive | delete
alphaswarm-cli brokers       list | providers | venues | add | test | remove
alphaswarm-cli accounts      list | show | create | positions | balance | orders | sync | summary
alphaswarm-cli bots          list | show | create | deploy | start | stop | restart | halt | halt-all | logs | versions | deployments | backtest
alphaswarm-cli agents        list | examples | describe | run | runs | show-run
alphaswarm-cli orchestration health | context | definitions | runs | show | events | artifacts | workers | pools | validate | compile | run | cancel | retry
alphaswarm-cli audit         list | stream
alphaswarm-cli status        system | probes | services
alphaswarm-cli config        get | set | show | diff | clear
alphaswarm-cli cp            deployments * | workloads * | cluster * | terraform * | cloudflare * | topology *
alphaswarm-cli manage        agents * | strategies * | backtests * | paper * | workflows *
alphaswarm-cli data          datasets * | sources * | sinks * | feeds *
alphaswarm-cli broker        venues * | credentials * | portfolio * | orders *
alphaswarm-cli deploy        plan | apply | up | down | refresh | status | logs | endpoints | build | publish-rpi
alphaswarm-cli viz           config | datasets | sync | export | import | render | cache-clear | datahub
alphaswarm-cli analysis      run | fetch
alphaswarm-cli results       list | show | export | clear
alphaswarm-cli routines      record | stop | run | list | show
alphaswarm-cli client        start | stop | status | logs | build | typecheck
alphaswarm-cli ide           install | build | start | stop | status | logs | open | url | env | detect | doctor
alphaswarm-cli connect       provision-cert | hosted | list | status | use | down | disconnect
alphaswarm-cli local         dev plan | dev init | dev build | dev up | dev connect | dev status | dev logs | dev down
alphaswarm-cli launch        up | down | restart | status | doctor | plan
alphaswarm-cli tools         generate-docs | bots ... | control-plane ... | admin-api ... | helpers *
alphaswarm-cli completions   diagnostics
alphaswarm-cli up | down | doctor   top-level aliases for `launch up` / `launch down` / `launch doctor`

Where State Lives

File / dir	Purpose
~/.config/alphaswarm/credentials/auth-session.json	Cached access/refresh/id tokens for CLI auth sessions.
OS keyring entry alphaswarm-cli	Tokens + M2M service-account profiles.
~/.config/alphaswarm/context.json	Active tenant context (org / project), set by context use.
~/.config/alphaswarm/topology.json	Cached topology snapshot.

Tenant-Aware Operations (Multi-Tenancy)

The CLI supports multi-tenancy by managing an active context:

1. Discovery: alphaswarm-cli context list shows organizations and projects.
2. Switching: alphaswarm-cli context use <org_id> [--project <id>] sets the active context.
3. Propagation: Headers like X-AlphaSwarm-Org are automatically added to requests.
4. Validation: Use alphaswarm-cli context show to verify effective identity.

AlphaSwarm IDE Entrypoint

alphaswarm-cli ide is the sanctioned way to manage the AlphaSwarm Theia IDE.

alphaswarm-cli ide install
alphaswarm-cli ide build --dev
alphaswarm-cli ide start --open

Local And Deployment Operations

Use alphaswarm-cli local dev as the recommended operator facade for personal or limited-scope local environments that run with the default personal-hosted-link profile.

alphaswarm-cli local dev plan
alphaswarm-cli local dev init
alphaswarm-cli local dev build
alphaswarm-cli local dev up
alphaswarm-cli local dev connect
alphaswarm-cli local dev status
alphaswarm-cli local dev logs
alphaswarm-cli local dev down

This flow delegates local backend lifecycle to alphaswarm-local while keeping hosted platform login explicit through:

alphaswarm-cli auth login --device --entra-tenant <tenantId>

If you use Azure CLI to find the tenant, az account show is only discovery for the active profile's tenant id. The platform login still happens through the AlphaSwarm CLI auth command above.

Use alphaswarm-cli local dev status to review local services, hosted auth, license state, tunnel state, and Connected Backends. Cloudflare DNS is deferred and unsupported for the first personal-hosted-link profile; use the hosted-link/device tunnel connection path.

Use alphaswarm-local init/up/link/status/doctor when you are debugging the lower-level local package primitives directly. Use alphaswarm-cli deploy and alphaswarm-cli cp for Terraform, topology, control-plane, and hosted deployment operations.

Further Documentation

• CLI Reference (alphaswarm_cli repo)
• Local Environment Lifecycle
• Onboarding New Org (alphaswarm_cli repo)
• Deploying First Bot (alphaswarm_cli repo)
• Platform Control Guide (alphaswarm_cli repo)
• AlphaSwarm Index (alphaswarm_index repo)