Skip to main content

Constellation CLI surfaces

Constellation ships two equivalent surfaces for interacting with Project Tracker (the dogfood instance that tracks our own work). Both call the same REST API; they exist for different agent runtimes.

pt CLI — for shell-based agents​

A thin Node CLI that wraps the PT REST API. Designed for shell-based AI agents (Claude Code, Cursor, Codex, Aider) that don't have an MCP runtime — every operation is a one-shot subprocess call. Zero per-agent setup.

npx pt workspace
npx pt list-tasks INF --status IN_PROGRESS
npx pt get-task INF INF-31 --json

Or from inside the monorepo:

npm --prefix tools/mcp-server run pt -- workspace

See the subcommand reference for the full list (18 subcommands as of the latest build).

constellation MCP server — for MCP-native clients​

A long-running MCP (Model Context Protocol) server that exposes the same surface as MCP tools. Designed for MCP-native agent runtimes (Claude Desktop, Claude Code's MCP integration, ChatGPT custom GPTs, anything that speaks the MCP protocol).

The server reads the same env vars as the CLI and calls the same REST endpoints — the only difference is the wire protocol (stdio JSON-RPC instead of subprocess invocation).

See MCP server setup for installation per agent runtime.

When to use which​

You are usingUse this
Claude Code (CLI), Cursor (terminal), Aider, Codexpt CLI. Zero setup, just npx pt.
Claude DesktopMCP server. Configure once in claude_desktop_config.json, then ask in chat.
Claude Code with .mcp.json configuredMCP server. Tools appear in the agent's tool list automatically.
ChatGPT custom GPTMCP server. Configure as a custom-GPT MCP connector.
You're not sureStart with the CLI — it's the simplest path.

Both authenticate the same way and hit the same backend, so an agent that uses one can switch to the other without losing access. The difference is purely ergonomic.

Authentication​

Both surfaces read the same environment variables:

VariablePurposeWhere to get it
PT_BASE_URLThe PT instance to connect to.https://constellation.planetb2b.com/projects for production
PT_AUTH_TOKENBearer JWT.Settings → API Keys page in the PT UI
PT_AUTH_COOKIEBrowser session cookie (fallback for PT_AUTH_TOKEN).Devtools → Application → Cookies

Both .env.local and .env at the monorepo root are auto-loaded by the CLI, so for local-dev work you usually only need to set them once.

Common flags​

Every subcommand supports:

  • --json — emit structured JSON output instead of human-readable Markdown. Use this in agent loops.
  • --help (or -h) — print the per-subcommand help. Top-level pt --help lists all subcommands.

See also​