Nebula CLI

nebula-ai puts your whole workspace in the terminal - the same agents, channels and calls you get in the desktop and mobile apps, without leaving your shell. Run it with no arguments for a full-screen app, or use its commands from scripts.

Install it

The npx option needs Node.js and npm. The Homebrew option needs Homebrew.

npx nebula-ai

brew install agent-labs-dev/nebula/nebula-ai

Sign in

Two ways to run it

nebula-ai opens the app. Most commands run once and exit, but chat --resume, call start and call join open interactive screens unless you choose their scripting options. See the command reference for the full list.

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.

You land in your Nebula room

The app opens on Home, which is a room: the running chat with Nebula, the orchestrator that runs your workspace. The header names it Nebula and the composer reads Message Nebula. Channels and your DMs with people open in the same view, so the header, the feed and the composer stay put and only the room changes.

Under the header, one strip holds the channel's four views - Chat, Tasks, Files and Channel - then any tabs you've opened from it, such as a thread's replies, a task or a call.

Tasks lists the channel's tasks, with its Jobs and Calls in their own sections underneath. Channel holds the channel's settings, and it's where you find its Members, Agents and Apps.

These are the keys that matter in a room.

Shift with P, A, R, V or D pins, archives, renames, recolours or deletes the channel you're in. A room with nothing in it yet shows the Nebula orb and No messages yet.

A chip under the composer names the model, and m opens the model picker. In a channel your pick becomes the channel's model for new tasks, not just yours; on Home it sets the model for your Nebula conversation. In a task's tab, m opens the picker for that task and Shift M cycles through your workspace's models.

Starting a call

Open the channel's Tasks view and choose Start a Call in its Calls section, or run nebula-ai call start from your shell. A call keeps running while you move around the app, and Ctrl G brings you back to it. See calls from the terminal for what the call screen does.

The channel rail

The left column, the channel rail, starts with your workspace's name - click it, or select it from the keyboard, to switch workspaces - then ⌂ Nebula (your Home), Mentions, your channels with a New Channel row, and then Members, the people in your workspace marked ● online, ◐ away or ○ offline. Computer control and Settings stay pinned at the bottom. Opening a person opens your DM with them, in the room view. Counts show what's unread, and Mentions carries the number of times you've been named.

Alt ↑ / ↓ walk the channels from wherever you are. To reach every row, press h or ← from a room's chat or a list: the bottom bar switches to RAIL, j / k move, g / G jump to the first row (the workspace name) and the last (Settings), Enter, l or → opens one - on the workspace name, the workspace switcher - and Esc hands the keyboard back. Search (Ctrl /) reaches the rest, including Notifications and Switch workspace.

Ctrl B hides the rail and shows it again, and the app remembers your choice between launches - it's the Hide Channel rail setting under Settings → CLI & TUI → Preferences. Pressing h while the rail is hidden brings it back. Below 100 columns it hides on its own, the workspace name moves into the title, and h opens search instead.

Whether agents can use this machine

To check whether agents can run commands on the computer you're typing on, choose Computer control at the bottom of the rail - the screen it opens is titled Computer Use - or run nebula-ai local-device status from your shell. The room header doesn't show it.

It describes this machine, not where a given reply ran. A channel's work runs on the devices that channel uses, and computer use from the CLI covers turning this machine on and choosing its working folder.

Tabs

1-9 jump to a stop on the strip by position: 1 to 4 are the four views, and any open tabs come next. Alt h / l step through the views and open tabs, even while you're typing. In a conversation - the chat, a thread's replies or a task - plain h / l or ← / → do the same, and they never open a thread on their way past; that's Enter's job. Ctrl W closes a tab, and Esc takes you back to the conversation.

Tasks continue in their thread

A task someone asked for in a channel message carries on in that message's thread, as it does in the desktop app. In the chat, the task's live card sits under that message: TASK and where it stands - Queued, Running, Paused, Needs your attention, Completed, Failed or Called off - then its title and a bar for its checklist, if it keeps one. While it runs, the card also shows what it's doing right now and the last few tools it used. When the message asked for more than one task, the card shows one, a running task ahead of finished ones, and says how many more are in the thread. Enter on the message, or a click on the card, opens the thread.

Opening a task from the Tasks view or from search opens the thread's replies too, headed by the same card. Press k past the first message to select the task and Enter to open its log, and v shows the message's other tasks when it asked for more than one.

That log is read-only. Where the composer would be, it reads Continue task in thread, and o or i takes you back to the thread to reply. A task with no message behind it, such as a job's run, keeps its own composer. In any task's tab, s stops it while it's answering.

When a task hands work to a coding agent, its log says how each hand-off ended - Done, Failed, Timed out, Lost, Interrupted or Cancelled - and, when one fails, why.

Slash commands

Typing / in the composer opens a palette of commands - Tab completes a name, Enter runs it. The CLI lists the full catalog Nebula offers for that conversation, your skills included, so it can show more than the desktop app's channel palette. In a task, 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.

Got an invite link? nebula-ai invite accept <link> joins that workspace and makes it your active one - paste the whole link, or just the token from it. And when you open the app with no workspace yet, it checks for invites to your email before asking you to name one.

What it can't do

Some integration actions need a choice the CLI cannot collect yet. On an app's page under Settings → Integrations, those actions are refused with a note that they need a choice the CLI can't ask for yet. Connecting and disconnecting with nebula-ai integrations works from the terminal.

Related