Command reference

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.

Not installed yet? Install the CLI first, then sign in with nebula-ai login.

Commands

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 or handle as its first argument.

Asking Nebula for the agent you need in any conversation still works, and creates it with whatever detail you describe. Connected apps aren't managed from the shell either: connect them in the full-screen app under Settings → Integrations, or see Connections.

Channels

channels manages channels and how they're set up - the same changes as a channel's settings in the full-screen app. Messages live under messages, and a channel's tasks and calls under tasks list --channel and call list --channel. Everything except list, create and archived takes the channel's handle as its first argument, and home names your own Nebula. (--help calls that argument <space>.)

Whether you can rename or delete a channel is Nebula's call for that channel, not the CLI's - when you can't, the command prints the reason it was given.

Messages

Every message command works in a channel - your own Nebula unless you pass --channel <handle> - or inside a task with --task <id>.

A thread is addressed by the ID of the message that started it, which messages list prints.

Inbox

The inbox holds the threads addressed to you, the same list the full-screen app's rail shows. A thread marked Done leaves your inbox until something new arrives in it.

Tasks

A task is one piece of work with its own conversation. Everything except list and create takes the task's ID as its first argument - tasks list prints it in the ID column, newest first.

tasks list --json and tasks get --json also print task_number, thread_root_id, waiting_on_user_id and created_at.

Read a task's conversation with messages list --task <id>, and add to it with messages send --task <id>.

nebula-ai chat --task <id> "…" sends to a task without opening it, and nebula-ai chat --resume <task-id> opens that task directly in the full-screen app.

Calls

The calls page covers what each of these feels like to use.

Scheduled tasks

The jobs commands manage scheduled tasks. Everything except list and create takes the job's ID or slug.

A new job starts as a draft: its agent writes the steps, and jobs resume turns it on.

Apps

The miniapps commands work on the workspace's apps. Put one on a channel with channels add-miniapp.

Skills

Skills for the whole workspace, or with --scope personal just for you.

Local device

The computer use page explains when you'd reach for each.

Account and workspace settings

Your profile, billing, connected apps, models, variables and devices aren't shell commands since CLI 0.1.24. Change them in the full-screen app under Settings, or in the desktop or mobile app. Product analytics can be turned off under Settings → Preferences → Telemetry, or with the DO_NOT_TRACK environment variable.

Billing

Settings → Billing in the full-screen app shows the Nebula Credits balance with the Tool Credits row under it, the auto top-up settings, and the latest credit transactions. Three actions sit under them: Edit auto top-up, Add balance and Refresh.

Billing is owner-only here, as it is in the desktop app. Anyone else - and a member whose role hasn't loaded yet - still sees the screen, with Edit auto top-up and Add balance greyed out and "Only the workspace owner can manage billing." beside them, rather than hidden.

Edit auto top-up sets whether auto top-up runs, the balance it tops up at and how much it adds, then saves them for Nebula Credits through the same billing rules the desktop app uses. It needs a card Stripe has on file: until the workspace has one, the toggle stays locked and the form says to subscribe or make a top-up first. A workspace with nothing saved starts at the defaults, a $1 threshold and a $10 top-up amount.

Add balance opens the web billing page in your browser, and prints the address when no browser can be opened. Adding a card and buying credits stay on the web, so the terminal never asks for card details.

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 use, so run nebula-ai local-device enable first - without a registered device, sessions fail with "Nebula local device is not configured."

Global flags

These work on every command.

Environment variables

Useful when you can't pass flags - CI, containers, a shared shell profile.

Scripting

--json turns any command into something you can pipe. It's a global flag, so it works the same everywhere.

tasks list --json emits a top-level array, so .[] works for the example above. A command that reads one thing, such as agents get, prints one object instead. Since CLI 0.1.22 the list and lookup commands print a fixed set of snake_case fields and nothing else, so a field the server adds later never shows up in your script; times are epoch milliseconds, and a field with no value is null. One that gets no answer within 30 seconds fails with "No answer came back in 30 seconds. Try again."

Exit codes and errors

A script can branch on the exit code instead of parsing what the command printed.

Exit 5 is the one to handle with care: sending again could repeat the work. Check nebula-ai messages list --task <id> first. nebula-ai status exits 3 when you're signed out, which makes it a cheap sign-in check.

Under --json, results stay on standard output and a failure is exactly one JSON line on standard error, with no colour codes:

The code is one of error, usage, auth_required or outcome_unknown. chat --json prints one object with thread_id, agent, status, final_message, events and pending - pending names the decision it's waiting on when status is waiting, and is null otherwise. A question the agent asks shows up in pending too, but status keeps reporting the turn itself and chat waits for the turn to finish instead of exiting 4 - the human-readable output tells you to answer it in Nebula or with nebula-ai chat --resume <id>.

Shell completion

nebula-ai completion prints a completion script for bash, zsh, or fish - source it from your shell profile.

When something goes wrong

Related