Appearance
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.
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 usuallyhttp://localhost:8000. - A developer API key from Developer Keys. Live keys start with
live_, test keys withtest_.
How it fits together
text
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.