@numacli/cli

Run your NUMA digital employee's tools from a terminal.

npm install -g @numacli/cli
numa login --focus <focus-mode-id>
numa tools
numa call <tool>          # pick one from `numa tools`

There is no model and no agent loop here — you name the tool and the arguments. That is what makes it usable from scripts, cron and CI, where an LLM choosing the tool would be a liability rather than a feature. It runs exactly the tools your administrator granted the employee, under the same permissions the chat interface uses.

Requirements

Node 20 or newer.

Signing in

numa login --focus <focus-mode-id> --base-url https://mcp.numa.team

A browser opens; approve the request. The token is stored in ~/.numa/tokens.json with 0600 permissions and renews itself silently, so you should not see the browser again for about a month.

Two things to know:

• A login authorises ONE digital employee, not your whole account. Signing in to another disconnects the first and revokes it — so a command can never act on an organisation you did not just authenticate.
• An administrator must enable CLI access for that employee. If it is off you get a clear refusal telling you so.

numa logout revokes the tokens at the server and removes them locally.

Configuration

Precedence: flag → environment → profile → config file → login.

export NUMA_BASE_URL=https://mcp.numa.team
export NUMA_FOCUS_UUID=<focus-mode-id>
numa config          # shows what resolved; the token is always redacted

Or ~/.numa/config.json:

{
  "defaultProfile": "prod",
  "profiles": {
    "prod":  { "baseUrl": "https://mcp.numa.team", "focusUuid": "…" },
    "test":  { "baseUrl": "https://mcp.numa.team", "focusUuid": "…" }
  }
}

numa tools --profile test

Commands

| Command | Does | | --- | --- | | numa login / numa logout | Sign in for one employee / sign out | | numa tools [--filter x] | List the tools this employee can run | | numa describe <tool> | Arguments, types, which are required | | numa call <tool> [args] | Run a tool | | numa info | Which employee you are pointed at | | numa config | Resolved configuration |

Passing arguments

# k=v — coerced: true/false/null, exact-round-trip numbers, otherwise text
numa call some-tool --arg query="SELECT id FROM account ORDER BY id" --arg limit:=5

# k:=<json> — explicit JSON, when coercion would guess wrong
numa call some-tool --arg ids:='[1,2,3]' --arg code:='"0010"'

# a whole payload
numa call some-tool --json '{"a":1}'
numa call some-tool --json @args.json      # or @- for stdin

Leading zeros survive. --arg code=01 stays the string "01". Numbers are only coerced when they round-trip exactly, because account codes, GL codes and document numbers are leading-zero strings — silently turning "01" into 1 returns the wrong rows rather than an error. k:= and --json settle anything ambiguous.

Unknown arguments are refused, not ignored. A mistyped optional argument would otherwise be dropped silently and the tool would run with defaults, which matters when the argument you fumbled was dryRun. Pass --allow-unknown-args to override.

Output

Default output is the tool's own JSON payload, pretty-printed and pipeable:

numa call some-tool | jq '.rows | length'
numa call some-tool --raw > export.csv     # text verbatim
numa call some-tool --envelope             # full MCP envelope, for debugging

Tool errors go to stderr with exit 1, so numa call … > out.json never writes an error message into your output file.

| Exit | Meaning | | --- | --- | | 0 | success | | 1 | the tool returned an error | | 2 | usage or configuration error | | 3 | connection or authentication failure |

Getting a focus mode id

Your NUMA administrator provides it — it identifies the digital employee and appears in that employee's connection settings.

Licence

MIT