Install

The CLI is one npm package and one config file. Install it, run mantis setup once to store your API key, space, and thread, and everything else is mantis use <tool> or mantis create ….

npm

npm install -g mantisai-cli
mantis setup
mantis use get_space_context

Naming

The repository is KellisLab/mantis-cli, but npm publishes it as mantisai-cli because mantis-cli was taken. The command it installs is mantis.

Once the CLI works, install skills for whichever editor you use:

Editor	Command
Claude Code	mantis setup claude
OpenCode	mantis setup opencode
Codex	mantis setup codex
Cursor	mantis setup cursor
Windsurf	mantis setup windsurf
GitHub Copilot	mantis setup copilot
Antigravity	mantis setup antigravity

mantis setup

Prompts for the API base URL and API key, then for a space and a thread only if they are not already set. Re-running it after your context is configured just refreshes credentials.

mantis setup

mantis setup does not install editor plugins and does not write an MCP server block into any editor config. Bare mantis setup configures credentials; mantis setup <provider> syncs skills. They are separate jobs.

Configuration

All CLI state lives in one file:

~/.mantis/config.json

The fields are apiBaseUrl, apiKey, spaceId, spaceName, spaceStateId (the thread), and spaceStateName. Inspect the resolved state with:

mantis status

mantis status exits non-zero when no thread is selected, which makes it a usable health check in scripts.

Switch workspace:

mantis select space
mantis select thread
mantis select          # both, in order

mantis select opens an interactive picker, so it blocks in a non-interactive shell. Agents should resolve the target first and then set it by UUID with mantis spaces set / mantis threads set. After any switch, the next mantis use picks up the new context automatically.

Command reference

Core

Command	Description
mantis setup [provider]	Configure credentials and context, or sync skills for one provider
mantis status	Config path, API base, MCP URL, key hint, space, thread
mantis select [space|thread|both]	Interactive space and thread picker
mantis version	Print the installed CLI version

Spaces and threads (JSON output)

Command	Description
mantis spaces list [--filter] [--offset] [--limit]	List accessible spaces. Page size defaults to 4.
mantis spaces resolve <link-or-uuid>	Resolve a space URL or UUID
mantis spaces set <uuid> [name]	Set the active space
mantis threads list [--filter] [--offset] [--limit]	List threads in the active space
mantis threads new [name]	Create a thread and make it active
mantis threads set <uuid> [name]	Set the active thread

These print JSON to stdout and errors as JSON to stderr, which is why the skills steer agents to them instead of the picker.

Create resources

Command	Description
mantis create map <file.csv>	Create a map from a local CSV
mantis create codebase [root]	Scan a repo into a CSV; add --create-map to embed it in one call

CSV only

mantis create map advertises XLSX in its help text, but the CLI reads the file as UTF-8 text and parses it as CSV before doing anything else. A real .xlsx workbook fails there. Convert to CSV first. The Mantis web uploader does accept spreadsheets; this is a client-side gap in the CLI.

Column typing is done with --<type>-column flags, all comma-separated: --title-column, --semantic-column, --numeric-column, --categoric-column, --date-column, --links-column, --custom-model-column, --image-column, --geospatial-column, --coordinate1-column, --coordinate2-column, --connection-column, --vector-column, and --delete-column to ignore a column. --data-types <json> passes a raw data_types array instead. Anything you do not type is inferred from the header row.

Space and activation flags are shared by both commands: --space-mode new|existing, --space-id, --space-name, --space-search, --public / --private, --map-name, --activate / --no-activate, --thread-name. mantis create codebase adds --out <file> and --max-chars <n> (12000 by default).

Run mantis create map --help or mantis create codebase --help for the full list.

Calling MCP tools

mantis tools                                  # every callable tool with its input schema
mantis use get_space_context                  # always run this first
mantis use inspect --uri "mantis://map/<id>"

Scalar arguments can be flags. Kebab-case maps to snake_case, so --map-id becomes map_id, and values are coerced to string, number, or boolean.

mantis use inspect --uri "mantis://map/<id>/cluster/<cid>" --depth 1

Complex arguments

Lists and objects cannot go through flags, because flag values are only coerced to scalars. Pass JSON instead, using whichever of the three mechanisms fits.

# Preferred: stdin. The shell never parses the JSON, so nothing can strip its quotes.
echo '{"query":"neural networks","kind":"point","scope":["mantis://map/<id>"]}' \
  | mantis use search --args-stdin

# From a file. Equivalent to stdin and better for large payloads.
mantis use filter_to_bag --args-file ./filters.json

# Inline. Works on POSIX shells; see the warning below.
mantis use filter_to_bag --args '{"numeric_filters":[{"field":"score","min":0.8}]}'

--args-file tolerates a UTF-8 or UTF-16 byte order mark, so a file written by a Windows editor is read correctly.

Inline JSON breaks on PowerShell and cmd

Those shells strip the inner quotes out of --args '{"k":"v"}' before the CLI ever sees it, and the data cannot be recovered afterward. The CLI detects the damage and stops with an explanatory error rather than forwarding garbage, but escaping harder does not help. Use --args-stdin or --args-file instead.

Empty arguments are rejected outright. On a mutating tool such as filter_to_bag, "no filter" would mean "match everything" and would bag the whole map.

Two things that trip people up

• search needs a scope in a multi-map space. Without scope, it returns scope_required. Pass "scope": ["mantis://map/<id>"].
• Field names are validated. Tools that take a field or dimension return {"error": "unknown_field", "available_fields": [...]} for a typo. Run mantis use inspect --uri "mantis://map/<id>/dimensions" to get the real names first.

See Overview for the tools the CLI blocks, and Local tools for the three that run locally instead of on the server.

Examples

New private space from a CSV

mantis create map ./data.csv \
  --space-mode new --space-name "Sales Q4" --private \
  --map-name "Pipeline" \
  --title-column name \
  --semantic-column description \
  --numeric-column revenue \
  --activate \
  --thread-name "Exploration"

Index a codebase

mantis create codebase . \
  --create-map \
  --space-mode new \
  --space-name "Repo Index" \
  --private \
  --map-name "Source Files" \
  --activate

With --create-map, the CSV columns are typed for you: path as title, summary,content,imports as semantic, language,kind,extension as categoric, and loc,bytes as numeric.

Paste a space link

During mantis setup or mantis select space you can paste a space URL instead of a UUID:

https://mantis.csail.mit.edu/space/1e1ed055-c869-4b78-b41f-4216a44049d4/

Use the API base URL that serves the space you are targeting.

Update

npm install -g mantisai-cli@latest

Skills are copied, not linked, so re-run mantis setup <provider> after upgrading or the editor keeps the old copies.

Troubleshooting

No thread configured. Every mantis use call requires a thread. Run mantis setup or mantis select thread.

API key errors. Create a new key at Developer Keys and re-run mantis setup.

Wrong space or stale map IDs. Run mantis use get_space_context again after switching space or thread. Never hand-edit ~/.mantis/config.json; the set commands keep space and thread consistent.

Could not parse --args as JSON. Your shell mangled the blob. Switch to --args-stdin or --args-file.

Read nextLocal toolsexport, project, and install_extension behave differently from every other tool.