CLI Reference

The orbital CLI is the main tool for local development, bootstrap, and admin workflows.

Quick start

# 1. Create and switch contexts
orbital context create local http://localhost:52000
orbital context list
orbital context use local   # or staging/production

# 2. Bootstrap first platform admin (no admins exist)
orbital invite ls                # Get bootstrap invitation code
orbital admin register <token>   # Register with passkey in browser
orbital admin login              # Login as platform admin

# 3. Check status
orbital admin status

Contexts are stored in ~/.orbital/config.yaml and hold API URLs and auth tokens per environment.

Platform Admin Invitations

Create Invitation Tokens

Generate invitation codes for new platform administrators (infrastructure-level):

# Create a new invitation
orbital invite create

Example output:

✅ Invitation created successfully!

Token:      cm4fj2k8r0001
Expires At: 2025-12-19T12:00:00Z

Signup URL: http://localhost:52000/api/_auth/signin?invite=cm4fj2k8r0001
Or use: orbital admin register cm4fj2k8r0001

Validate Invitations

Check if an invitation token is valid:

# Check if invitation is valid
orbital invite get cm4fj2k8r0001

List invitations

orbital invite list

# Works without auth in bootstrap mode (no admins yet)

Contexts

Switch contexts

# Switch active context
orbital context use production

# Short alias
orbital ctx use staging

# Show current context
orbital context show

Context-Specific Operations

orbital ctx use local
orbital admin status

orbital ctx use staging
orbital admin status
orbital invite create

orbital ctx use production
orbital admin status

Common checks

Switch between contexts to test different environments:

# Test local
orbital ctx use local
orbital admin status

# Test staging
orbital ctx use staging
orbital admin status

Configuration File

Location: ~/.orbital/config.yaml

current: local
contexts:
  local:
    api_url: http://localhost:52000
    auth_token: eyJhbGc...  # Platform admin JWT (stored after login)
  staging:
    api_url: https://staging-api.orbital.io
    auth_token: ""
  production:
    api_url: https://api.orbital.io
    auth_token: ""

Command reference

Context

Manage API contexts for different environments.

Command	Description
`orbital context list`	List all contexts
`orbital context create <name> <url>`	Create a new context
`orbital context use <name>`	Switch active context
`orbital context show`	Show current context details
`orbital context delete <name>`	Delete a context

Aliases: ctx

Platform Admin Authentication

Manage platform administrator authentication (infrastructure-level).

Command	Description
`orbital admin register <token>`	Register as platform admin using invitation token (opens browser)
`orbital admin login`	Login as platform admin with passkey (opens browser)
`orbital admin logout`	Clear platform admin authentication token
`orbital admin status`	Show current platform admin authentication status
`orbital admin token`	Print raw JWT token (for scripting)

Platform Admin Invitations

Manage platform administrator invitations. Works without authentication in bootstrap mode.

Command	Description
`orbital invite create`	Create a new platform admin invitation token (requires auth)
`orbital invite ls`	List all platform admin invitations (works in bootstrap mode)
`orbital invite get <token>`	Validate and view invitation details
`orbital invite delete <token>`	Delete an invitation (requires auth)

Aliases: invitations, inv

Streams

Subscribe to real-time event streams.

Command	Description
`orbital stream list`	List available streams
`orbital stream subscribe <name>`	Subscribe to a stream (e.g., wallet, heartbeat)

Aliases: str

Example:

orbital stream list
orbital str subscribe wallet

Orb Management

Manage orbs, modules, schemas, and entries using path-based addressing.

Paths follow the structure: orbId[/moduleId[/entryId]]

Smart routing: Single-schema modules omit schemaId in paths.

Command	Description
`orbital apply -f <file>`	Create or update orb from YAML/JSON
`orbital get <path>`	Get resource details by path
`orbital ls [path]`	List resources (depth based on path)
`orbital delete <path>`	Delete a resource
`orbital create <path> --data '{...}'`	Create an entry
`orbital call <orbId>/<primitive>`	Call a primitive function

Path Examples:

# List resources at different levels
orbital ls                             # List all orbs
orbital ls accounts                    # List modules in orb
orbital ls accounts/operators          # List entries (single-schema module)

# Get specific resources
orbital get accounts                   # Get orb definition
orbital get accounts/operators/abc123  # Get specific entry

# Create/update from file
orbital apply -f accounts.yaml         # Create orb with modules/schemas
orbital apply -f operator.yaml         # Create entry

# Create entry with inline data
orbital create accounts/operators --data '{"email":"[email protected]"}'

# Call primitives
orbital call accounts/bootstrap                           # Bootstrap accounts orb
orbital call accounts/passkey/begin --data '{"email":"[email protected]"}'

# Delete resources
orbital delete accounts/operators/abc123

For detailed platform documentation, see Platform Architecture.

Global Flags

Flag	Description
`-v, --version`	Show CLI version
`-h, --help`	Show help information

Troubleshooting

Authentication Issues

If you’re having trouble authenticating as platform admin:

# Check if you're authenticated
orbital admin status

# Clear and re-authenticate
orbital admin logout
orbital admin login

API Connection Issues

Verify your API connection:

# Check current context
orbital context show

# List all contexts
orbital context list

# Verify server is running
curl http://localhost:52000/api/_orbs

Context Issues

Reset to default configuration:

# Remove existing config
rm ~/.orbital/config.yaml

# Create new context
orbital context create local http://localhost:52000
orbital context use local