Mantis CLI

mantis is a command-line client for Mantis. It holds your API key and active workspace context in a local config file, creates maps from local files, and proxies every Mantis MCP tool through mantis use <tool>. Coding agents drive it by running shell commands, so no editor needs a native MCP plugin.

KellisLab/mantis-cliThe published npm package is `mantisai-cli`; the command it installs is `mantis`.npm: mantisai-cli

These pages describe mantisai-cli 3.7.

What you get

Capability	How
Auth and context	API key, active space, and active thread stored in ~/.mantis/config.json
Map creation	mantis create map from a local CSV, or mantis create codebase to index a repo
MCP tools	mantis use <tool> proxies the Mantis MCP server, with mantis tools listing what is callable
Local tools	export, project, and install_extension run in the CLI itself, not on the MCP server
Agent skills	mantis setup <provider> writes SKILL.md files for seven editors

Requirements

• Node.js 18 or newer.
• A Mantis API base URL. The default is https://kellis-h200-1.csail.mit.edu; a local backend is usually http://localhost:8000.
• A developer API key from Developer Keys. Live keys start with live_, test keys with test_.

How it fits together

agent  →  reads SKILL.md  →  runs `mantis use …` / `mantis create …`
              ↑
        mantis setup <provider>

Every invocation reloads ~/.mantis/config.json and sends Authorization: Bearer <key> plus, for MCP calls, X-Space-State-ID: <thread> to <api-base>/mcp_integrated/. Because the context is read fresh each time, switching space or thread takes effect on the next command with no reconnect step.

Agent workflow

Whenever Mantis comes up, the agent runs mantis use get_space_context first. That returns the active space, its maps as mantis:// URIs, and enough schema to make the next call correct. Every bundled skill states this rule.

mantis use fails immediately if no thread is configured. Run mantis setup or mantis select thread to fix it.

Blocked MCP tools

The CLI hides twelve server tools from mantis tools and refuses them from mantis use, each for a different reason.

Blocked tool	Why	Use instead
create_space	Space creation should be an explicit, human-visible act	mantis setup or mantis select space
create_map_from_url, modify_map_from_url	Same, for maps	mantis create map or mantis create codebase
cite_file	Needs an agent sandbox (an X-Chat-ID and a live container) that the CLI cannot provide. It works only for in-sandbox claude_code / opencode agents.	Nothing equivalent from the CLI
add_cell, edit_cell, delete_cell, execute_cell, get_cell, get_cell_count, check_task_status	Notebook cell tools round-trip through the notebook UI and are not meant for agent or CLI use	Work in Mantis Coding directly
export	Blocked as an MCP passthrough, then re-injected as a CLI-local tool that writes a parquet file to your disk	mantis use export, see Local tools

Editor integrations

mantis setup <provider> copies the CLI’s bundled skills into the directory the editor watches. Seven providers are supported:

Provider	Command	Skills written to
Claude Code	mantis setup claude	~/.claude/skills/
OpenCode	mantis setup opencode	~/.config/opencode/skills/ and ./.opencode/skills/
Codex	mantis setup codex	~/.agents/skills/ (add --project for ./.agents/skills/)
Cursor	mantis setup cursor	~/.cursor/skills/
Windsurf	mantis setup windsurf	~/.codeium/windsurf/skills/
GitHub Copilot	mantis setup copilot	~/.copilot/skills/
Antigravity	mantis setup antigravity	~/.agents/skills/ and ./.agents/skills/

Invocation syntax differs per editor: /mantis in Claude Code and Cursor, $mantis in Codex, @mantis in Windsurf and Antigravity. Any other agent that can run shell commands works too, but it will not get the skills, so tell it to run mantis use get_space_context yourself.

Documentation

Install

npm install, `mantis setup`, the command reference, and calling MCP tools.

Local tools

`export`, `project`, and `install_extension`, which touch your disk instead of the MCP server.

Claude Code

`mantis setup claude`, the five slash commands, and troubleshooting.

OpenCode

Global and project skill paths, and why not to add an MCP block.

Codex

USER and REPO scopes, `$mantis` invocation, disabling a synced skill.

Other editors

Cursor, Windsurf, Copilot, and Antigravity.

Security

Treat developer API keys like passwords. Do not paste them into chats, issues, or screenshots, and revoke an exposed key from the developer portal immediately.

The CLI reaches only the space and thread named in your local config, using the permissions of the key’s owner. It stores the key in plaintext in ~/.mantis/config.json.

Read nextInstall the CLIGet from npm install to your first tool call.