Command Reference

Complete reference for all lobster CLI commands.

Authentication

`lobster login`

Authenticate with LobsterCage. Opens your browser for OAuth login.

`lobster logout`

Clear local credentials.

`lobster whoami`

Display the currently authenticated user and account details.

Migration

`lobster migrate`

Scan your current environment, detect the project type and platform, analyze resource usage, calculate cost savings versus LobsterCage, and optionally migrate the agent into a cage.

Designed to be run by either a human operator or the agent itself.

Option	Description
`--dry-run`	Analyze only — do not create a cage
`--json`	Output as JSON (ideal for agent self-migration)
`--dir <path>`	Project directory to scan (default: current directory)
`--cost <amount>`	Current monthly hosting cost in dollars
`--yes`	Skip confirmation prompt (for non-interactive use)


lobster migrate                    # Interactive scan + migrate
lobster migrate --dry-run          # Analyze without migrating
lobster migrate --json             # Machine-readable output
lobster migrate --cost 14          # Specify current monthly cost
lobster migrate --dir /opt/mybot   # Scan a different directory
lobster migrate --json --yes       # Agent self-migration (no prompts)

Cage Management

`lobster create <name>`

Create and start a new cage. (Alias: lobster deploy)


lobster create my-agent

`lobster list`

List all cages in your account with their current status.


lobster list

`lobster status <name>`

Show detailed status for a specific cage, including state, size, webhook URL, and uptime.


lobster status my-agent

`lobster destroy <name>`

Permanently delete a cage and its associated resources. This is irreversible.


lobster destroy my-agent

`lobster config <cage>`

View or update cage configuration such as idle timeout.

Option	Description
`--show`	Show current cage config
`--idle-timeout <minutes>`	Set idle timeout in minutes (1-1440, 0 = max / never hibernate)
`--json`	Output as JSON


lobster config my-agent --show              # View current config
lobster config my-agent --idle-timeout 60   # Set idle timeout to 1 hour
lobster config my-agent --idle-timeout 0    # Disable auto-hibernate (set to max)
lobster config my-agent --show --json       # JSON output

Lifecycle

`lobster start <name>`

Start a stopped or hibernated cage.


lobster start my-agent

`lobster stop <name>`

Stop a running cage. Data is preserved.


lobster stop my-agent

`lobster hibernate <name>`

Hibernate a running cage. Stops compute but preserves storage. The cage can be woken by webhooks, cron, or manual wake.


lobster hibernate my-agent

`lobster wake <name>`

Wake a hibernated cage.


lobster wake my-agent

Connections

`lobster ssh <name>`

Open an SSH session to a running cage.


lobster ssh my-agent

`lobster exec <name> [cmd]`

Execute a single command in a cage and return the output.


lobster exec my-agent "ls -la /workspace"

`lobster port-forward <name>`

Forward a local port to a port inside the cage.


lobster port-forward my-agent

`lobster tunnel <name>`

Create a raw tunnel to a cage for custom transport.


lobster tunnel my-agent

`lobster dashboard <name>`

Open the cage’s dashboard page in your browser.


lobster dashboard my-agent

`lobster ssh-config`

Generate and install SSH config for LobsterCage cages. Adds a Host *.lobster block to ~/.ssh/config so you can connect with ssh agent@my-cage.lobster, VS Code Remote SSH, scp, sftp, etc.

Option	Description
`--print`	Print the config block without installing
`--remove`	Remove the LobsterCage SSH config block


lobster ssh-config               # Install config into ~/.ssh/config
lobster ssh-config --print       # Preview the config block
lobster ssh-config --remove      # Remove the LobsterCage config block

Environment Variables

`lobster env list <name>`

List all environment variables set on a cage (names only, values hidden).


lobster env list my-agent

`lobster env set <name> KEY=value`

Set one or more environment variables. Values are encrypted at rest.


lobster env set my-agent BOT_TOKEN=abc123 API_KEY=sk-xyz

`lobster env get <name> KEY`

Retrieve the decrypted value of a specific environment variable.


lobster env get my-agent BOT_TOKEN

`lobster env delete <name> KEY`

Remove an environment variable.


lobster env delete my-agent BOT_TOKEN

`lobster env scan <name>`

Scan a local .env file and set all variables on the cage.


lobster env scan my-agent

API Keys

`lobster apikeys list`

List all API keys for your account.

`lobster apikeys create`

Create a new API key with specified scopes.


lobster apikeys create

`lobster apikeys revoke <keyId>`

Revoke an API key.


lobster apikeys revoke ak_abc123

Billing

`lobster billing status`

Show current credit balance, plan details, and recent usage.


lobster billing status

`lobster billing portal`

Open the Stripe billing portal in your browser to manage subscriptions and view invoices.


lobster billing portal

`lobster upgrade`

Upgrade your plan.


lobster upgrade

Logs

`lobster logs <name>`

Fetch recent logs from a cage.


lobster logs my-agent

`lobster tail <name>`

Stream logs from a cage in real time.


lobster tail my-agent