Command reference
Every nebula-ai command and subcommand, plus the global flags, environment variables, JSON output for scripting, shell completion, and the logs.
Every nebula-ai command, what it does, and the flags that apply everywhere. Run nebula-ai <command> --help for the options on any one of them — that output is generated from the binary you have, so it's always current.
Commands
| Command | What it does |
|---|---|
login | Authenticate with Nebula via device-flow pairing |
logout | Clear stored credentials |
status | Show CLI status overview |
usage | Show workspace token usage and cost — --days <n> sets the window |
chat | Send a message to an agent DM and stream the response |
call | Voice calls — see below |
channels | Manage channels — see below |
agents | Manage agents — see below |
workspace | Manage workspaces — list, switch, create |
integrations | Connect and manage workspace integrations — see below |
models | List and manage the models this workspace can use — see below |
user | Your profile and account settings — see below |
profile | Your public profile — get, set, set-email, verify-email, upload-avatar |
local-device | Manage computer control and the local device daemon — see below |
install | Set up computer control — an alias of local-device enable |
uninstall | Turn off computer control, stop the daemon, and remove this device |
capabilities | Probe and print this host's capability snapshot |
logs | Inspect Nebula log files on disk — logs path prints the directory |
update | Check for a newer CLI version and install it |
completion | Generate a shell completion script |
acp | Run Nebula as an editor agent over the Agent Client Protocol |
Run nebula-ai with no command at all to open the full-screen app.
Agents
Everything except list and create takes the agent's ID as its first argument.
| Command | What it does |
|---|---|
agents list | List agents |
agents create | Create a new agent |
agents get | Get agent details |
agents update | Update an agent |
agents delete | Delete an agent |
agents enable | Enable an agent |
agents disable | Disable an agent |
agents logs | Get agent logs |
agents errors | Get agent errors |
agents triggers | List triggers for an agent |
agents accounts | Show which account an agent acts as, and what else it could use |
agents set-account | Choose which connected account an agent acts as |
agents skills list | List skills attached to an agent |
agents skills detach | Detach a skill from an agent |
An agent doesn't pick up your connected accounts on its own — you choose one per
app. agents accounts <id> is how you see where that stands from a terminal: it
lists your connected accounts with an In use column, so a connected account
reading no is exactly what a stalled tool is waiting for.
The toolkit is implied by the account you name, so there's no separate flag for it. Only the agent's owner can set this — the binding decides which of their identities the agent spends.
To give an agent a new skill, ask Nebula to install it from a link. See Skills and slash commands.
Channels
| Command | What it does |
|---|---|
channels list | List channels |
channels create | Create a new channel |
channels get | Get channel details |
channels status | Show the channel's work status |
channels update | Update a channel |
channels messages | List messages in a channel |
channels share | Share a channel |
channels archive | Archive a channel |
channels unarchive | Unarchive a channel |
channels delete | Delete a channel |
nebula-ai chat --resume <channel-id> skips all of this and opens that channel
directly in the full-screen app.
Calls
The calls page covers what each of these feels like to use.
| Command | What it does |
|---|---|
call start | Start a call and open the call screen |
call join <thread> | Join an existing call |
call list <thread> | List a channel's calls, live ones first |
call status <thread> | Show the state of one call |
call chat <thread> | Send a one-shot typed message into a call |
call leave <thread> | Leave a call you're in |
call end <thread> | End the call for everyone |
Integrations
| Command | What it does |
|---|---|
integrations list | List integration connections |
integrations connect <provider> | Connect a workspace integration |
integrations disconnect <provider> [account] | Disconnect a workspace integration account. The account ID is only needed when more than one is connected |
Models
Which models this workspace can use, and which one it falls back to. Curating the catalog and setting the default need workspace admin or owner; listing doesn't. See Models and defaults.
| Command | What it does |
|---|---|
models list | List selectable models — Nebula tiers, curated, and custom |
models default [model] | Show the workspace default, or set it (admin only) |
models curate | Show which vendor models the workspace offers |
models curate --add <ids...> | Add vendor models to the curated list |
models curate --remove <ids...> | Remove vendor models from the curated list |
models custom list | List custom models visible in this workspace |
models custom add <name> | Add a custom model — see the flags below |
models custom remove <model-id> | Delete a custom model you own |
models custom add takes --alias <model-id> to create a routing alias to a catalog
model, or --base-url <url> with --model-id <id> to point at your own
OpenAI-compatible endpoint. Add --auth <value> for an authorization header,
--device <device-id> to lock the model to one machine, and --share to make it
visible to the whole workspace instead of just you. See
Bring your own model for what each of those means.
Local device
The computer control page explains when you'd reach for each.
| Command | What it does |
|---|---|
local-device enable | Turn on computer control and start the daemon |
local-device disable | Turn off computer control and stop the daemon |
local-device status | Show computer-control and daemon status, and check with the server which workspace this machine is bound to |
local-device logs | View daemon logs |
local-device start | Start the daemon |
local-device stop | Stop the daemon |
local-device restart | Restart the daemon |
local-device exec-mode get | Show the current execution mode |
local-device exec-mode set <mode> | Set whether agents can run commands on this host |
Account commands live under user
Anything that belongs to your account rather than the workspace is nested one
level down, so nebula-ai user on its own prints a summary of who you're
signed in as.
| Command | What it does |
|---|---|
user update | Update your username or display name |
user variables | Manage user variables — list, set, create, delete |
user config | Manage CLI configuration — see below |
user billing | Manage credits — balance, history, auto-topup |
user files | Manage files — see below |
user devices | Manage your cloud devices — see below |
CLI configuration
| Command | What it does |
|---|---|
user config list | List all configuration values |
user config get <key> | Get a configuration value |
user config set <key> <value> | Set a configuration value |
user config reset | Reset all settings to defaults |
user config models | List available AI models |
user config set telemetry false turns product analytics off. The
DO_NOT_TRACK environment variable does the same
thing without touching your config.
Files
| Command | What it does |
|---|---|
user files list | List files |
user files get <id> | Get file details |
user files content <id> | Print a text file's contents |
user files upload <path> | Upload a file |
user files download <id> | Download a file |
user files share <id> | Create a shared link for a file |
user files folders | List folders |
user files delete <id> | Delete a file |
Cloud devices
These are your cloud devices, not the machine you're typing on
— that one is local-device.
| Command | What it does |
|---|---|
user devices info | Get your device info |
user devices start | Start your device |
user devices stop | Stop your device |
user devices rename <name> | Rename your device |
user devices visibility <true|false> | Make the device visible to your workspace, or keep it private |
user devices files | List files on the device |
user devices search <pattern> | Search device files by filename glob |
user devices delete | Delete your device |
user devices services list | List device services |
user devices services get <name> | Get service details |
user devices services create <name> | Create a long-running service |
user devices services start <name> | Start a service |
user devices services stop <name> | Stop a service |
user devices services logs <name> | Get service logs |
Changing your email address
Your email is the one profile field you can't set outright — changing it takes proof that you can receive mail at the new address, so it runs in two steps.
Run nebula-ai profile set-email <address>. Nebula mails a six-digit code
to the new address and tells you your current address hasn't changed yet.
Run nebula-ai profile verify-email <code> with the code from that mail.
Only then does the address actually change.
Codes expire after 15 minutes; request another with set-email if yours runs
out. nebula-ai profile get marks an address that hasn't been confirmed yet
with (unverified).
Using Nebula from your editor
nebula-ai acp runs Nebula as an agent over the Agent Client Protocol,
speaking on standard input and output rather than drawing anything itself. Point
an editor that speaks ACP at that command and Nebula answers inside the editor,
with the same agents and channels you get everywhere else.
Each session is scoped to the directory the editor opens it in, and that
directory becomes the working folder the agent reads and writes in. The scoping
comes from computer control, so run
nebula-ai local-device enable first — without a registered device, sessions
fail with "Nebula local device is not configured."
Run it by hand and it will sit there silently waiting for protocol messages. That's correct behaviour, not a hang — press Ctrl C to exit.
Global flags
These work on every command.
| Flag | What it does |
|---|---|
--json | Output raw JSON |
--workspace <id> | Run against a specific workspace, ignoring the active one |
-v, --verbose | Verbose output — the same as --log-level=debug |
--log-level <level> | One of error, warn, info, debug, trace |
--no-color | Disable colours |
--api-url <url> | Point at a different API host |
Environment variables
Useful when you can't pass flags — CI, containers, a shared shell profile.
| Variable | What it does |
|---|---|
NEBULA_AUTH_TOKEN | Use a pre-minted token instead of the stored credential. Takes precedence over whatever login saved |
NEBULA_API_BASE | Point at a different API host — the same thing --api-url does |
NEBULA_WEB_URL | Point the links the CLI opens, such as sign-in, at a different Nebula host |
NEBULA_HOME | Override ~/.nebula, where credentials, settings, and logs live |
NEBULA_LOG_LEVEL | One of error, warn, info, debug, trace — the env form of --log-level |
NEBULA_DEBUG | Set to true for verbose logging — the same as -v |
DO_NOT_TRACK | Set to 1 to turn product analytics off. NEBULA_DO_NOT_TRACK works too |
NEBULA_AI_NO_UPDATE_CHECK | Set to 1 to skip the daily update check |
NEBULA_AI_CACHE_DIR | Override where npx nebula-ai caches the downloaded binary |
NEBULA_AI_DOWNLOAD_BASE | Download that binary from a mirror instead — useful behind a strict firewall |
NEBULA_AUTH_TOKEN is the one to reach for in CI. It skips the device-flow
browser handoff entirely, which a build agent can't complete anyway.
Scripting
--json turns any command into something you can pipe. It's a global flag, so it works the same everywhere.
List commands emit a top-level array under --json, so .[] is the right entry point rather than reaching through a wrapper.
The columns a command prints don't always match its JSON field names. Run the command once with --json and read the shape before writing the jq.
Combine --json with --workspace in CI so a script never depends on whichever workspace happened to be active on that machine.
Shell completion
nebula-ai completion prints a completion script for bash, zsh, or fish — source it from your shell profile.
When something goes wrong
nebula-ai status shows whether you're signed in and which workspace you're pointed at — most surprises are one of those two. nebula-ai capabilities reports what this machine supports, like whether ffmpeg is available for camera.
nebula-ai logs path prints the directory the log files live in (~/.nebula/logs/), ready to pipe into your pager. Re-run a failing command with -v for the detail.
nebula-ai update checks for a newer version and installs it. Worth trying before reporting anything.
Still stuck? Ask Nebula directly — it's good at drafting a support email with the right detail in it. For bugs or anything unresolved, email support@nebula.gg.
Related
Computer control from the CLI
Turn any machine into a Nebula local device with one command — choose whether agents can run commands, manage the daemon, and know where they work from.
Calls from the terminal
Start, join, and run Nebula calls from your shell. Chat-first by default, with voice as a two-step opt-in and a headless mode for servers.