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 — the CLI mirrors most of the constellation MCP server's PT-scoped tool surface, though a handful of MCP tools (e.g. create_stage, reorder_stages, find_user, resolve_key) have no CLI equivalent (see MCP server setup § What's exposed as MCP tools for the current mapping).

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​

Log in once — there is no token to mint or paste:

export PT_BASE_URL=https://constellation.planetb2b.com/projects
npx pt login

This runs an OAuth loopback + PKCE flow in your browser and stores a per-user rotating credential in ~/.config/constellation/credentials.json (0600), outside the repo. The pt CLI and the stdio MCP server read it. (The hosted Streamable HTTP endpoint does not — it authenticates per request via connector OAuth or a Bearer header.) npx pt whoami shows who you are and which credential source resolved; npx pt logout revokes it server-side.

For Claude Code, register the server once per machine, from your main checkout (claude mcp add writes Claude Code's config only):

claude mcp add constellation -s user \
  -e PT_BASE_URL=https://constellation.planetb2b.com/projects \
  -e WIKI_BASE_URL=https://constellation.planetb2b.com/wiki \
  -- npx -y tsx "$(pwd)/tools/mcp-server/src/index.ts"

Claude Desktop (claude_desktop_config.json), Codex (~/.codex/config.toml), Cursor, Aider, and hosted (Streamable HTTP) clients each register differently — see MCP server setup for the canonical per-runtime detail.

A login lasts ~30 days per consent (the short-lived access token underneath is refreshed automatically). The 30-day refresh-family expiry is a ceiling absolute from consent — it does not slide with use — and a role change or token reuse can end the session sooner, so you re-run pt login when it lapses.

VariablePurposeWhere to get it
PT_BASE_URLThe PT instance to connect to. Required — it keys the stored profile.https://constellation.planetb2b.com/projects for production
PT_AUTH_TOKENCI / headless only. Static Bearer JWT; takes precedence over pt login.Settings → API Keys page in the PT UI
PT_AUTH_COOKIEBrowser session cookie; also takes precedence over pt login.Devtools → Application → Cookies

.env.local and .env at the monorepo root are auto-loaded by the CLI. Set PT_BASE_URL there; do not leave a PT_AUTH_TOKEN or PT_AUTH_COOKIE behind for local work — resolution order is env → store, so a stale value of either silently overrides your pt login until it expires or is revoked. npx pt whoami names the source that actually resolved.

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​