Skip to main content
Rigbox exposes a local command surface and an in-workspace surface. Most commands behave the same in both; a few stay on your machine. The generated command pages identify which modes support each command and show separate syntax when flags differ.

​
Local terminal

Install the CLI on your machine and authenticate with rig login. Use this mode to create workspaces, configure your account, upload a local application, and manage resources across workspaces.
When a command requires an identifier, use the identifier returned by the preceding list or create operation. Do not assume workspace-mode examples accept the same local flags.

​
Inside a workspace

Every workspace has the CLI installed at /usr/local/bin/rigbox, with rig linked to it. It is signed in as the workspace and reaches Rigbox through the workspace bridge, so you don’t run rig login there. Connect with SSH or the console terminal, then run commands as usual:
These commands work inside a workspace:

​
Commands that stay on your machine

Run these from your local terminal. Inside a workspace, each one refuses before doing anything, with one line that says why and where it works: For example:
The command exits with status 1. With --output json, the refusal is a single error event with "code":"unsupported", even when the flag comes after the command’s own arguments. A command that reaches a route the bridge doesn’t serve fails the same way, with one line that names the request.

​
Choose the workspace

Inside a workspace, commands act on that workspace. rig workspace logs, ssh-info, env, and ai take no --workspace at all, and rig workspace metrics, ports, services, resize, and reconcile and rig app expose-port use the current workspace when you leave --workspace out. Commands that still require --workspace, such as rig tools, rig volume, rig snapshot create, rig build image, rig app-release, and rig recipe app install, need this workspace’s own name or ID; the bridge serves no other workspace.

​
Deploy from inside a workspace

rig deploy inside a workspace deploys the project into that workspace. It ignores workspaces bound in .rig.lock and never creates a new one:
Options that would clone, re-image, or replace the machine the command runs on refuse before any work starts: --workspace naming another workspace, --bluegreen, --promote, --reimage, and image deploys (reproducible: true or strategy: image). Run those from your machine.

​
Output, queries, and logs

--output json (or yaml, text, table), --query, and the output default you save with rig config set output work inside a workspace too. rig workspace logs --follow and rig app logs --app APP --follow print new lines as they arrive; where the log stream isn’t available inside the workspace, they poll every few seconds instead. Press Ctrl-C to stop following.

​
What a workspace can’t change

The bridge acts for the workspace’s owner but serves only what code inside one workspace should be able to do. It doesn’t serve API keys or account SSH keys, and it serves account-wide settings (AI defaults, setup scripts, and service specs) read-only. Code running in a workspace, including an AI agent, therefore can’t add a key that reaches your other workspaces or change a script that runs in them.

​
Keep the CLI current

rig update updates the CLI in a workspace in place, and workspaces also update it on their own every day. When a newer release is out, commands print a notice pointing at rig update. See Update the CLI.

​
Resolve a command mismatch

Run rig --version and rig COMMAND --help in the terminal where the command failed. Check the mode section on that command’s reference page. A workspace’s installed version may differ from your local installation; run rig update in the workspace to bring it up to date. This reference describes CLI v0.13.0-rc.5 (revision 824aefd). Continue with authentication or configuration and output.