TopoloCli

Command-line interface for the Topolo platform. Designed for both humans and third-party agents (Claude Code, Codex, Cursor, etc.) that prefer to interact via stdin/stdout.

Current scope

• API-key authentication (long-lived, service-scoped).
• Access-token authentication via OAuth device flow when a CLI OAuth client id is configured.
• Stored access-token refresh when the config includes a refresh token and OAuth client id.
• Commands: auth login/logout/status, whoami, apps, apps scaffold, services, crm contacts:list, crm contacts:get, and generic api passthrough for SDK-registered services.

Install

npm install -g @topolo/cli
# or run ad-hoc:
npx @topolo/cli whoami

Configure

Credentials come from (in priority order):

1. TOPOLO_API_KEY env var
2. TOPOLO_ACCESS_TOKEN env var
3. Config file ($XDG_CONFIG_HOME/topolo/config.json, mode 0600)

For interactive use:

topolo auth login --client-id doac_...  # device flow
topolo auth login --api-key topo_live_... # store API key directly
topolo auth status           # shows which source is active
topolo auth logout           # clears the stored credential

If no client id is configured, topolo auth login falls back to an API-key prompt in an interactive terminal. Non-interactive sessions should pass --api-key or set TOPOLO_CLI_CLIENT_ID.

Cross-org isolation

The CLI never accepts an orgId argument. Every command is scoped to the organization embedded in the credential. This is enforced in two places:

1. The SDK does not expose any orgId parameter on any public method.
2. Each Topolo backend app re-derives orgId from the credential on every request and binds it to SQL query filters.

There is no code path in the CLI that could ever let you read or mutate another organization's data.

Audit headers

Every outbound request carries:

• X-Topolo-Client: topolo-cli/<version>
• X-Topolo-Agent: <label> (if TOPOLO_AGENT_NAME is set)
• X-Topolo-Request-Id: <uuid>

The platform logs these for traceability.

Write-action gating

The SDK defaults to requiring an explicit --confirm flag on any mutating request. The generic topolo api passthrough enforces this too:

topolo api crm POST /api/contacts --data '{"email":"[email protected]"}' --confirm

Commands

topolo whoami

Prints the user, organization, and granted scopes.

topolo whoami           # pretty
topolo whoami --json    # machine-readable

topolo crm contacts:list

topolo crm contacts:list
topolo crm contacts:list -q "acme" -p 2 -s 50 --json

topolo crm contacts:get <id>

topolo crm contacts:get contact_abc123

topolo services

Lists every service id and effective URL known to the generated SDK registry.

topolo services --json

topolo apps

Lists every Topolo application known to the generated SDK catalog, including pages-only applications that do not expose a callable API service.

topolo apps --json
topolo apps get mail --json
topolo apps requirements mail --json
topolo apps audit mail --json
topolo apps audit mail --local --repo-root /Users/ashes/Projects/topolo --fail-on needs_review --json
topolo apps scaffold insights --json
topolo apps scaffold insights --write --repo-root /Users/ashes/Projects/topolo --json
topolo apps scaffold score --target developer --write --repo-root ./starters --json
topolo apps scaffold insights --workflow-only --no-json

Agents should call topolo apps requirements <app> --json before creating or expanding a Topolo app. The output is the versioned platform contract for app metadata, canonical docs, shared auth, shared shell, service registration, deployment metadata, agent surfaces, observability, and verification. topolo apps audit --json turns the same contract into per-app scores and a catalog-backed migration queue. Add --local --repo-root <topolo-checkout> to include filesystem evidence from the app repo, CloudControl metadata, and TopoloDocs. Add --fail-on needs_review for the default new-work gate, or --fail-on partial for strict release readiness.

topolo apps scaffold <app> generates the required new-application scaffold, including package/auth/shell/docs/CloudControl files, a deploy-ready Wrangler Worker/static-assets baseline, an Auth service manifest, and a topolo-conformance.yml GitHub Actions workflow for first-party platform apps. Add --write --repo-root <topolo-checkout> to create the files on disk; existing files are refused unless --force is passed. The generated workflow checks out the app under PlatformApplications/<AppDir>, checks out Topolo-io/docs, Topolo-io/topolo-sdk, and Topolo-io/TopoloCli, builds the current CLI from source, then runs the local conformance audit with --fail-on needs_review.

For third-party developers, use --target developer or --developer. Developer scaffolds are standalone starter projects with topolo.app.json, .env.example, an OAuth authorization-code + PKCE browser starter, and no internal TopoloDocs, CloudControl, or private first-party package dependencies. Developer scaffolds are browser-only by default; add --with-api to include a protected Worker baseline that validates bearer tokens through Topolo Auth over HTTP.

topolo api <service> <method> <path>

Escape hatch for endpoints without typed modules yet.

topolo api auth GET /api/me
topolo api crm POST /api/contacts --data '{"first":"Jane"}' --confirm

Use topolo services --json to discover valid service ids before calling a service that does not have a typed command yet.

Output modes

• Pretty when stdout is a TTY.
• JSON when piped or redirected.
• Force either with --json / --no-json.

Exit codes

| Code | Meaning | | ---- | ----------------------- | | 0 | Success | | 1 | Generic error | | 2 | Auth error | | 3 | Permission denied |

Development

cd TopoloCli
npm install
npm run build
node dist/index.js whoami

Agent skills

Installable guides for agents that drive the CLI on behalf of a user.

• Claude Code — copy skills/topolo/ into ~/.claude/skills/ (per-user) or <your-project>/.claude/skills/ (per-project). Claude picks it up automatically when the description matches the user's request.
• Codex / Cursor / generic — drop skills/codex/AGENTS.md at the root of your repo (or alongside the code your agent works in). Codex reads AGENTS.md files by convention.

Both docs cover the same CLI surface: credential handling, the JSON invocation contract, the write-safety --confirm guardrail, and the cross-org isolation rules. Keep them in sync when adding new commands.

For agents that support MCP, also register @topolo/mcp; the skill/AGENTS guidance still matters because it tells the agent when to prefer MCP tools, when to fall back to shell commands, and how to handle writes.

Debug output

Set TOPOLO_DEBUG=1 to trace every SDK request to stderr (stdout stays clean so --json piping still works):

TOPOLO_DEBUG=1 topolo whoami
# [topolo] → GET auth /api/auth/me (req=8f3...)
# [topolo] ← 200 GET auth /api/auth/me (142ms, req=8f3...)

Request IDs match the X-Topolo-Request-Id header, so you can correlate a failing CLI call with the backend access log. Accepted truthy values: anything except 0 or false.

Token auto-refresh

If the stored access token is within 60 s of expiry, the CLI transparently exchanges the stored refresh token for a new pair before making the request and rewrites the config — no user action required. The OAuth client_id used at login is persisted alongside the credential so refresh can re-authenticate.

If refresh fails (network, rotated/revoked refresh token), the CLI proceeds with the stale credential and the request returns auth_error — run topolo auth login to re-authenticate. The stored config is not cleared on transient refresh failures.