Nebula CLI
Run Nebula from your terminal. Install the nebula-ai CLI, sign in once, and use the full-screen app to chat, join calls, and drive your workspace.
nebula-ai puts your whole workspace in the terminal — the same agents, channels, threads and calls you get in the browser, without leaving your shell. Run it with no arguments for a full-screen app, or with a command to do one thing and exit.
Install it
npx nebula-aiThe first run downloads the binary for your platform, verifies it, and caches it. After that it starts instantly.
brew install agent-labs-dev/nebula/nebula-aiInstalls nebula-ai onto your PATH so you can run it from anywhere.
Sign in
Run nebula-ai login. It uses device-flow pairing, so the terminal shows you a code and hands off to your browser.
Approve it in the browser with the same account you use on the web.
You're done. Run nebula-ai on its own to open the app, or go straight to a command.
Unlike the desktop app, the CLI does not renew its pairing on its own. When a code expires it tells you to run nebula-ai login again — that's expected, not a fault.
Two ways to run it
| The full-screen app | One-off commands | |
|---|---|---|
| How | nebula-ai | nebula-ai <command> |
| Best for | Working in Nebula for a while | Scripts, CI, a quick question |
| Machine-readable | — | yes, with --json |
| Interactive | Yes | only where the command asks |
Anything with no arguments opens the app; anything with arguments runs and exits. See the command reference for the full list.
There's a third mode: nebula-ai acp hands the whole thing to your editor
instead of your shell. See using Nebula from your editor.
Getting around the app
The app is keyboard-driven and modal, like a modal editor. In navigation mode the keys move you around; press i to start typing and Esc to come back out. The bar along the bottom always names the mode you're in and the keys that matter on this screen.
| Key | What it does |
|---|---|
| ? | Opens the shortcuts help — the full list, always current |
| Ctrl K | Search across your workspace |
| j / k | Move down / up |
| Enter | Open the selected item |
| Esc | Go back, or leave typing mode |
| i / c | Write a message / start a call |
| Ctrl F | Find in the thread you're reading |
| @ | Jump to Agents |
| b | Jump into the sidebar |
| q | Quit |
Don't memorise these — ? lists every shortcut for the screen you're on, including ones this page doesn't cover.
The home screen
Home is a starting point, not a feed. You get the Nebula orb, a Talk to Nebula entry that starts a call, and the composer. Press i to write, c to call, and Tab to move between the workspace line at the top, the call entry, and the composer.
The line under the composer shows which model tier will answer — Shift M cycles it. Where a message will actually run is named at the top of the screen instead: Computer Control sits on the right of the workspace line, on or off for the workspace you're in. Send from here and it runs wherever that says — on your machine if you've approved this folder, in the cloud sandbox otherwise.
The sidebar
The left column mirrors the web app's sidebar: Home, Notifications, Agents, Jobs, Mini Apps, Calls, Devices, Settings, then your channels and recent threads. Rows carry the same signals you'd expect — an unread count, a dot while an agent is working, a marker when something needs you.
Press b, or press ← from the leftmost tab. Then j / k to move and Enter to open — which hands focus back to the main area.
Ctrl B rests it as a narrow rail, and again brings it back. Nebula remembers which you prefer.
Below about 100 columns it starts as the rail on its own, showing a single › at the left edge. Press b to peek it open — it returns to the rail when you leave.
Finding something in a long thread
Ctrl F opens a find bar over the thread you're reading. Type and it counts the hits as you go — 3/12 — or says no matches. Enter and Ctrl N move to the next hit, Ctrl P to the previous, and Esc closes the bar and leaves you where you landed. It searches the thread you're in, not the workspace — Ctrl K is the one for that.
Two places tell you where work runs
The terminal names the machine twice, and they answer different questions. Read them as next and now.
| The line above the composer | The chips on the status line | |
|---|---|---|
| Tells you | Where your next message will run | Where this thread has been running |
| Changes when | You switch folder or device | You open a different thread |
| Shows | ☁ cloud sandbox, or your device and folder | The thread's device, then its folder |
They agree most of the time. They come apart when you open a thread that started somewhere else — a thread run on your laptop, opened from a terminal in the cloud sandbox — and that's exactly when you want to notice.
Tabs
The app keeps tabs, the same way the web app does. 1–9 jump to a tab, h and l step between them, and x closes the current one. Home can't be closed.
Slash commands
Typing / in the composer opens the same slash commands you get on the web — Tab completes a name, Enter runs it. Pressing c on a message that mentions a command explains it instead of running it.
Picking a workspace
Your session has an active workspace, and every command uses it unless you say otherwise.
nebula-ai workspace switch <id-or-slug> changes the active workspace for everything that follows.
The global --workspace flag overrides it for a single command, which is what you want in a script.
nebula-ai workspace list prints them all; nebula-ai status shows who you're signed in as and where you're pointed.
What it can't do
The CLI drives the same backend as everything else, so the gaps are narrow and deliberate. The one you'll hit in practice is that actions needing a choice — picking a channel or a workspace from a list, renaming a connection — are refused with a note to use the web app instead. Everything else in nebula-ai integrations works from the terminal.
Stuck? Ask Nebula in any conversation — it can explain commands and set things up for you. For bugs or anything unresolved, email support@nebula.gg.
Related
Push notifications
Turn on push notifications for the Nebula mobile app, manage which of your phones receive them, and choose what they tell you about.
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.