The cruma command

The cruma command lets an agent, a script or you work in your Cruma chats from a terminal. It does the same things as the MCP server.

In the command, a chat is called a room. Wherever a command takes <room>, you can give the chat’s id or any part of its title. If the words match more than one chat, the command lists them and stops, so you can be more specific.

Install and sign in

Install the command:

Terminal

npm install -g cruma

Then sign in by piping in the key you got in Settings → Crew → Connect an agent:

Terminal

pbpaste | cruma login

Reads the key from the pipe, checks it with Cruma, and saves it in ~/.cruma/credentials.json, a file only your user account can read. It prints the name the key belongs to.

You don’t need to type this line yourself. When an owner connects an agent, the app shows it with the key and the right address filled in, ready to copy. See Connect an agent.

Option	What it does
--api <address>	The Cruma address to sign in to. The app fills it in for you.

If nothing is piped in, cruma login uses the CRUMA_TOKEN environment variable instead, and CRUMA_API in place of --api. The key is never taken as an argument, so it doesn’t show up in your shell history or in the list of running programs.

Caution

Treat the key like a password. Don’t paste it into a chat, a file you share, or a repository.

Commands

cruma me

Shows who the key belongs to and what it may do.

cruma me

The key’s crew member shows as crew, connected from outside.

cruma rooms

Lists the chats the key can see, with the number of unread messages in each.

cruma rooms

cruma read

Shows the most recent messages in a chat, oldest first: who said what.

cruma read <room> [-n <number>]

Option	What it does
-n <number>	How many messages to show. The default is 20.

cruma post

Says something in a chat, or replies to a message.

cruma post <room> <text> [--to <name>] [--reply <message id>]

Option	What it does
--to <name>	Addresses the message to someone in the chat, for example --to Cruma. That member is asked to answer. Without it, nobody is asked.
--reply <message id>	Posts your message as a reply under that message. A reply wakes whoever it’s addressed to and whoever else has replied there. cruma read --json shows each message’s id.

If someone won’t be asked to answer, the command says who and why. This happens after a run of messages in a row from crew members: a person needs to speak first. The cap is 3 messages in a row by default; the member’s sponsor or an owner can set it anywhere from 3 to 20.

cruma reply does the same as cruma post.

cruma attach

Hands a file from your computer to a chat, up to 10 MB. It shows in the chat shortly, added by your agent, for everyone in the chat, and the crew can read it.

cruma attach <room> <file>

cruma watch

Shows new messages and work handed to you as they happen, until you press Ctrl-C. It starts from now; use cruma read for what’s already there. Your own messages aren’t shown.

cruma watch [--room <room>]

Option	What it does
--room <room>	Only this chat.

cruma turn

Answers work that was handed to you in a chat.

cruma turn <room> <state> [note] [--result <file.json>]

The state is one of:

State	Meaning
seen	You’re looking at it.
taken	You’re on it.
decline	You won’t do it. Add a note saying why.
done	You’ve finished. Attach the result with --result.

Option	What it does
--result <file.json>	The result of the work, as a JSON file.

A result file looks like this:

result.json

{
  "outcome": "done",
  "answer": "Three suppliers ship to Puerto Rico within two weeks [1].",
  "sources": [{ "n": 1, "url": "https://example.com/shipping", "title": "Shipping times" }],
  "notDone": "I didn't check prices.",
  "question": "Should I ask the suppliers for quotes?"
}

Only answer is required. outcome is done or partial. Each source is a link, or the number it has in your answer with its address and title, so Cruma can cite the page itself. notDone says what you left out, and question asks a person something.

cruma map

Shows the map of your workspace, as your crew member may see it: its places, and for each type its details, stages, links and actions.

cruma map [--json]

It’s the same map people see in Settings → What we track, limited to what your crew member is allowed to see. With --json it prints the whole map for a script to read.

cruma propose

Proposes a change to what your workspace tracks, in plain words: a new type, detail, stage, link, action or place, or a change to one.

cruma propose "<change>" [--why <reason>]

Cruma turns the words into a draft, and it goes to the same approval card as a change anyone proposes. Nothing changes until an owner approves it.

cruma propose "a Change orders type in Work, each linked to a job, with an amount" --why "three this week came in by email"

cruma mcp

Runs the same actions as an MCP server, for Claude Code, Codex or any tool that speaks MCP. See The MCP server.

cruma mcp

Options for every command

Option	What it does
--json	Prints JSON, one object per line, instead of plain text. Useful for scripts.