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:80
orbital context list
orbital context use local   # or staging/production

# 2. Bootstrap first admin (no admins exist)
orbital invite list
orbital auth register <token>
orbital auth login

# 3. Check status
orbital auth status

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

Invitations

Create Invitation Tokens

Generate invitation codes for new users to sign up:

# 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/auth/signin?invite=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 auth status

orbital ctx use staging
orbital auth status
orbital invite create

orbital ctx use production
orbital auth status

Common checks

Switch between contexts to test different environments:

# Test local
orbital ctx use local
orbital auth status

# Test staging
orbital ctx use staging
orbital auth status

Configuration File

Location: ~/.orbital/config.yaml

current: local
environments:
  local:
    api_url: http://localhost:80
    auth_token: eyJhbGc...  # 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

Authentication

Command	Description
`orbital auth register <token>`	Open browser to register with an invitation token
`orbital auth login`	Browser-based login, stores CLI token in config
`orbital auth logout`	Clear authentication token
`orbital auth status`	Show current authentication status

Invitations

Command	Description
`orbital invite create`	Create a new invitation token
`orbital invite list`	List invitations in current environment
`orbital invite get <token>`	Validate an invitation token

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

Global Flags

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

Troubleshooting

Authentication Issues

If you’re having trouble authenticating:

# Check if you're authenticated
orbital auth status

# Clear and re-authenticate
orbital auth logout
orbital auth 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:80/health

Context Issues

Reset to default configuration:

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

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