CLI

Overview

The ArchAstro CLI provides command-line access to every platform operation. It uses a verb-first syntax (archastro <verb> <resource>) and supports --json output for scripting and CI/CD pipelines.

---

Installation

# Configure npm registry for @archastro scope
# Add to ~/.npmrc:
@archastro:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

npm install -g @archastro/developer-platform-cli

Verify:

archastro --help

---

Authentication

The CLI uses browser-based OAuth device flow:

archastro auth login

This opens your browser to developers.archastro.ai/cli-auth, starts a local callback server, and stores credentials in ~/.config/archastro/credentials.json (mode 0600). Tokens are scoped per-app and refreshed automatically.

archastro auth status    # Show current auth state
archastro auth logout    # Remove all stored credentials

---

Project initialization

cd my-project
archastro init

init opens your browser for app selection (or creation), generates API keys, and writes archastro.json to your project root:

{
  "app_id": "app_abc123",
  "sandbox_id": "sbx_optional",
  "configs": {
    "enabled": true,
    "directory": "configs"
  }
}

---

Settings

archastro settings get                # Show all settings
archastro settings set app <id>       # Set default app
archastro settings set api-url <url>  # Override API URL
archastro settings set portal-url <url>
archastro settings reset              # Reset to defaults
archastro settings path               # Show config file path

---

Resource commands

All resources support a consistent verb pattern:

Apps

archastro list apps
archastro describe app <id>

API keys

archastro list appkeys
archastro create appkey -t publishable    # or -t secret
archastro revoke appkey <id>

Secret keys are shown once at creation — copy immediately.

Agents

archastro list agents
archastro list agents --search "support"
archastro describe agent <id>
archastro create agent -n "Support Agent" -k support-bot \
  -i "You are a customer support specialist"
archastro create agent -n "Alex" --profile-picture ./avatar.png
archastro update agent <id> -n "Senior Support Agent"
archastro delete agent <id>

Agent flags: -n/--name, -k/--lookup-key, -e/--email, -p/--phone, -i/--identity, --team-id, --user-id, --profile-picture.

Users

archastro list users
archastro list users --search "john@example.com"
archastro describe user <id>
archastro create user -e alice@example.com -n "Alice"
archastro create user --system-user    # bot account, no login
archastro delete user <id>

Teams

archastro list teams
archastro list teams --search "engineering"
archastro describe team <id>
archastro create team -n "Engineering" -d "Engineering department"
archastro update team <id> -n "New Name"
archastro delete team <id>

Threads

archastro list threads
archastro describe thread <id>

Automations

archastro list automations
archastro list automations --type trigger
archastro list automations --type scheduled
archastro describe automation <id>
archastro create automation -n "Welcome Email" -t trigger --trigger "user.created"
archastro create automation -n "Daily Report" -t scheduled --schedule "0 8 * * *"
archastro update automation <id> -n "New Name"
archastro activate automation <id>
archastro pause automation <id>
archastro delete automation <id>

Files

archastro list files
archastro list files --team-id <id>
archastro describe file <id>
archastro create file --data "base64..." --filename "doc.pdf" --content-type "application/pdf"
archastro update file <id> --filename "renamed.pdf"

Environment variables

archastro list appenvvars
archastro describe appenvvar <id>
archastro create appenvvar -k WEBHOOK_SECRET -v my_secret -d "Webhook signing secret"
archastro update appenvvar <id> -v new_value
archastro delete appenvvar <id>

Webhooks

archastro list appwebhooks
archastro describe appwebhook <id>
archastro create appwebhook -p github -s signing_secret
archastro update appwebhook <id> --enabled false
archastro delete appwebhook <id>

OAuth providers

archastro list appoauthproviders
archastro describe appoauthprovider <id>
archastro create appoauthprovider -p github \
  --client-id abc123 --client-secret xyz789 \
  --callback-urls "https://app.example.com/auth/github"
archastro update appoauthprovider <id> --enabled false
archastro delete appoauthprovider <id>

Domains

archastro list appdomains
archastro create appdomain -d example.com
archastro delete appdomain <id>

---

Organization management

archastro list orgs
archastro describe org <id>
archastro create org -n "Acme Corp" --slug acme --domain acme.com
archastro update org <id> -n "Acme Corporation"
archastro delete org <id>
archastro org invite -e alice@example.com -r developer   # or -r admin
archastro org remove <member_id>
archastro org invites                                     # list pending

---

Sandbox management

See Sandboxes for the full guide.

archastro list sandboxes                                    # * marks active sandbox
archastro describe sandbox <id>
archastro create sandbox -n "Staging" -s staging
archastro activate sandbox                                  # opens browser to scope CLI to sandbox

Sandbox keys

archastro list sandboxkeys --sandbox <id>
archastro create sandboxkey --sandbox <id> -t publishable   # or -t secret
archastro revoke sandboxkey <key_id> --sandbox <id>

Sandbox emails

archastro list sandboxmails --sandbox <id>
archastro describe sandboxmail <email_id> --sandbox <id>
archastro delete sandboxmail <email_id> --sandbox <id>
archastro delete sandboxmails --sandbox <id> --all

---

Agent extensions

Agent computers

archastro list agentcomputers --agent <id>
archastro describe agentcomputer <id>
archastro create agentcomputer --agent <id>
archastro delete agentcomputer <id>

Agent working memory

archastro list agentworkingmemory --agent <id>

System configs

Browse and clone platform-provided config templates.

archastro list systemconfigs
archastro describe systemconfig <id>
archastro clone systemconfig <id>

---

Configuration management

The CLI can sync configs between your local filesystem and the server, enabling version-controlled config workflows.

Enable config sync

During archastro init, opt in to config management. This creates a configs/ directory and a .archastro-manifest.json file that tracks server mappings.

Pull configs from server

archastro configs sync                          # pull all
archastro configs sync --dry-run                # preview changes
archastro configs sync --on-conflict overwrite  # overwrite local on conflict
archastro configs sync --kind api-gateway       # sync specific kind
archastro configs sync --prune-local            # delete locally-tracked configs removed on server

Push configs to server

archastro configs deploy                        # push all
archastro configs deploy --dry-run              # preview changes
archastro configs deploy --prune                # archive server configs deleted locally
archastro configs deploy -m "Update API rules"  # with change message

Other config operations

archastro configs content <id>                  # show raw content
archastro configs kinds                         # list available kinds
archastro configs sample <kind>                 # show sample config
archastro configs sample <kind> --to-file f.yaml
archastro configs validate -k workflow --content "..."
archastro configs archive <id>
archastro configs edit <path>                   # open in browser editor
archastro configs new [filename]                # create in browser editor
archastro configs mv <from> <to>               # update manifest after move
archastro configs manifest-repair               # fix manifest inconsistencies

---

Scripting with JSON output

All commands support --json for machine-readable output:

# Get all agent IDs
archastro list agents --json | jq -r '.data[].id'

# Create a user and capture the ID
USER_ID=$(archastro create user -e bot@example.com --system-user --json | jq -r '.id')

# Pipe to other tools
archastro list teams --json | jq '.data[] | select(.name | contains("Eng"))'

---

Shell completion

eval "$(archastro completion bash)"   # add to ~/.bashrc
eval "$(archastro completion zsh)"    # add to ~/.zshrc
archastro completion fish | source    # or save to completions dir

---

Configuration files

File	Purpose
~/.config/archastro/config.json	CLI settings (default app, URLs)
~/.config/archastro/credentials.json	Auth tokens (mode 0600)
./archastro.json	Project config (app ID, sandbox, config sync)
./configs/.archastro-manifest.json	Config sync state

---

Environment variables

Variable	Purpose
ARCHASTRO_DEV_API_URL	Override API base URL
ARCHASTRO_DEV_PORTAL_URL	Override portal URL

---

Generated command index

The full command index below is auto-generated from the CLI source.