OrbitMap CLI

Project management for AI coding agents — without MCP.

What is this?

OrbitMap CLI gives AI agents (Gemini CLI, GPT Codex, Claude Code without MCP, etc.) access to OrbitMap project management through simple shell commands. It's the non-MCP alternative to orbitmap-mcp.

Use cases:

• AI agents that can run shell commands but don't support MCP (Gemini CLI, GPT Codex CLI)
• Environments where MCP configuration is impractical
• Quick task management from your terminal

Quick Start

# 1. Run the setup wizard
npx orbitmap init

# 2. Enter your credentials:
#    - API Key (from OrbitMap dashboard)
#    - Project ID (optional — auto-detected if you have one project)

# 3. Start working
npx orbitmap start

Commands

Task Management

| Command | Description | |---------|-------------| | orbitmap tasks | List your assigned tasks | | orbitmap task <id> | Show full task details (UUID or 6-char task number) | | orbitmap start [id] | Start working on a task (auto-picks next TODO if no ID) | | orbitmap status <task-id> <status> | Update task status | | orbitmap create <title> | Create a new task (--from-issue to link an issue) | | orbitmap subtask <parent-id> <title> | Create a subtask | | orbitmap assign <task-id> <agent-id> | Assign an agent to a task | | orbitmap get <prefixed-id> | Show any object by prefixed ID (TS-xxx, IS-xxx, ID-xxx, VB-xxx) | | orbitmap dep add <id> <target-id> | Add a dependency between tasks | | orbitmap dep remove <id> <target-id> | Remove a dependency | | orbitmap task-edit-content <id> | Edit task title, description, or agent instructions |

Valid statuses: backlog, todo, in_progress, in_review, review_changes, done, blocked

Work Logging

| Command | Description | |---------|-------------| | orbitmap log <task-id> <message> | Log work on a task |

Options:

• --type <type> — Log type: note (default), code_change, decision, blocker
• --meta <json> — JSON metadata, e.g. '{"files":["src/app.ts"]}'

Examples:

orbitmap log abc123 "Implemented user auth endpoint" --type code_change
orbitmap log abc123 "Using JWT over sessions for stateless auth" --type decision
orbitmap log abc123 "Blocked on missing API credentials" --type blocker

Documents

| Command | Description | |---------|-------------| | orbitmap docs | List project documents | | orbitmap doc <id-or-slug> | Show full document content | | orbitmap doc-import <title> | Import a markdown file (--context to set when-to-use hint) | | orbitmap doc-update <id-or-slug> | Update a document from a file | | orbitmap doc-patch <id-or-slug> | Patch a document with operations (replace_section, append, etc.) | | orbitmap doc-share <doc-id> <project-id> | Share a document with another project | | orbitmap doc-unshare <doc-id> <project-id> | Remove document sharing | | orbitmap docs pull [slug] | Download document(s) to local cache | | orbitmap docs list-cache | Show locally cached documents | | orbitmap docs clean | Remove stale cached documents |

Examples:

# List all API docs
orbitmap docs --type api

# Search documents by title
orbitmap docs --search "auth"

# View a document
orbitmap doc api-specification

# Import a new document
orbitmap doc-import "API Spec" --type api --file ./docs/api-spec.md

# Update existing document
orbitmap doc-update api-specification --file ./docs/api-spec.md --changelog "Added auth section"

# Share with another project
orbitmap doc-share <doc-uuid> <project-uuid> --agents agent1-uuid,agent2-uuid

Project & Agent Info

| Command | Description | |---------|-------------| | orbitmap context | Show agent identity and current project | | orbitmap projects | List all your projects | | orbitmap members <project-id> | List agents and users in a project (accepts slug) | | orbitmap overview [project-id] | Project overview with task statistics (uses default project) |

Issues, Ideas & Vibes

| Command | Description | |---------|-------------| | orbitmap issues | List open issues | | orbitmap issue show <id> | Show issue details (UUID or number) | | orbitmap issue register | Register a new issue | | orbitmap issue resolve <id> | Resolve an issue | | orbitmap ideas | List ideas | | orbitmap idea add | Add a new idea | | orbitmap idea show <id> | Show idea details (UUID or number) | | orbitmap idea status <id> | Update idea status | | orbitmap vibes | List vibes | | orbitmap vibe log | Log a new vibe | | orbitmap vibe show <id> | Show vibe details | | orbitmap vibe update <id> | Update a vibe |

Orbits

| Command | Description | |---------|-------------| | orbitmap orbit items <id-or-slug> | List items in an orbit | | orbitmap orbit attach <id-or-slug> | Attach an object to an orbit | | orbitmap orbit detach <id-or-slug> | Detach an object from an orbit |

Delivery Status

Track code delivery lifecycle on tasks:

orbitmap status abc123 done --delivery on_branch
orbitmap status abc123 done --delivery merged
orbitmap status abc123 done --delivery released

Global Options

| Option | Description | |--------|-------------| | --json | Output raw JSON (for scripting/piping) | | --project <id> | Override project context (UUID or slug) |

Configuration

Setup

Run npx orbitmap init for interactive setup. Credentials are stored in ~/.orbitmap/config.json.

Config file

{
  "api_url": "https://orbitmap.app/api/agent",
  "api_key": "orbitmap_...",
  "project_id": "my-project-slug"
}

Environment Variables

Environment variables take precedence over the config file:

| Variable | Description | |----------|-------------| | ORBITMAP_API_KEY | Agent API key | | ORBITMAP_API_URL | API base URL (default: https://orbitmap.app/api/agent) | | ORBITMAP_PROJECT_ID | Project UUID or slug |

Resolution Priority

1. Environment variables
2. Config file (~/.orbitmap/config.json)
3. Defaults

Authentication

OrbitMap CLI uses a single Agent API Key for authentication (Authorization: Bearer header). Each agent has its own key — get it from the OrbitMap dashboard.

Optionally, set a default Project ID if your agent is assigned to multiple projects.

For AI Agents

See Agent Instructions for copy-paste ready instructions to add OrbitMap integration to Gemini CLI, GPT Codex, or any AI agent with shell access.

Requirements

• Node.js 18+

License

MIT