Quick Start

Before you start

You need Node.js 20 or newer and either an interactive Topolo account or an API key. The CLI, public Docs, and credential-scoped application/action catalog are sufficient on a clean computer; a Topolo source checkout is not required.

1. Install and identify yourself

npm install --global @topolo/cli
topolo --version
topolo auth login
topolo setup
topolo doctor
topolo auth status --json
topolo whoami --json

auth login opens the Topolo authorization flow. The final two commands should return authenticated JSON containing the active identity and context. For a headless process, set TOPOLO_API_KEY from a secret manager and run the same status and identity checks. Do not put the key in source control or a command transcript.

2. Select the correct context

topolo context ls --json
topolo context use personal --json

Replace personal with an organization context returned by context ls when the work belongs to that organization. Context is part of authorization: do not try to override it with an organization id in an action payload.

If this computer hosts multiple agent contexts, add a separate pinned MCP registration after selecting the exact context name:

topolo setup --name topolo-acme --context org:org_acme --env production
topolo doctor --name topolo-acme
topolo skills status --name topolo-acme --json

This does not change the interactive CLI context. Use a distinct topolo-* name for each customer organization and run the named-registration doctor before handing the registration to an agent host.

When that customer context is decommissioned, remove only its named registration and verify that it is gone:

topolo skills uninstall --name topolo-acme --json
topolo skills status --name topolo-acme --json

Do not uninstall the shared default registration while other agents still use it.

3. Discover the service and actions

topolo apps --json
topolo services --query web --json
topolo actions --service web --json
topolo actions capabilities --service web --json

Choose an application from the returned catalog, then choose a published action. The action catalog is more precise than a prose route list because it includes the exact endpoint, permission, input and output schemas, confirmation policy, effects, examples, verification, and recovery contract.

You can browse the same public contract in Agent Actions: enter a service such as topolo-web, browse its actions, and select one. Docs never exposes the action's private runtime origin.

4. Inspect and validate one exact contract

This read-only sequence uses the published TopoloWeb build action as a concrete example:

topolo actions get app_topolo_web.sites.build --json
topolo actions examples app_topolo_web.sites.build --json

Copy a published example input into payload.json, replace example placeholders with your intended values, then validate and plan locally:

topolo actions validate app_topolo_web.sites.build --data @payload.json --json
topolo actions plan app_topolo_web.sites.build --data @payload.json --json

Validation must succeed before planning. The plan should identify the resolved request, effects, whether confirmation is required, verification steps, and any published rollback action. Planning does not execute the mutation.

5. Execute only after approval

Read-only actions can execute without mutation confirmation. For a write action, inspect the complete plan and obtain approval before running:

topolo actions call app_topolo_web.sites.build --data @payload.json --confirm --json

After the call, perform every verification step returned by the action contract. If verification fails, preserve the request id and use only the published recovery or rollback action; do not guess a private route.

MCP equivalent

topolo setup installs the public Topolo skill and registers the exact compatible MCP server bundled with the CLI. Customers install only @topolo/cli; no separate MCP or SDK installation is required. The equivalent tool sequence is topolo_whoami, topolo_search_applications, topolo_search_actions, topolo_get_action, topolo_validate_action, topolo_plan_action, and then topolo_read_action or topolo_call_action as allowed by the contract.

The public surface contains identity, organization context, live application and resource discovery, OAuth, and catalog actions. First-party scaffolding, Seed, fleet audits, provisioning, deployment, and release operations are restricted platform tooling and are not customer commands.

Troubleshooting checkpoints

• auth status fails: sign in again or replace the expired API key.
• An application is absent: verify the active context; discovery is credential-scoped.
• An action is absent: search by capability and service before concluding it is unavailable.
• Validation fails: change only the reported input paths and validate again.
• Planning reports confirmation: stop for approval; do not bypass it.
• A 403 is returned: the target runtime denied the concrete request; do not widen scope or retry with guessed identifiers.
• Schema, examples, effects, verification, or recovery are missing: report a documentation publication defect and stop the affected operation.

Change Log / Verification

• Updated the clean-machine path on 2026-08-14 to use the single-package topolo setup and protocol-level topolo doctor flow, documented pinned multi-organization registrations and their status/uninstall lifecycle, corrected the mutation MCP tool name, and documented the customer/platform boundary. Reverified the complete temporary-agent-home lifecycle against @topolo/cli@0.8.8 and its 20-tool MCP server.
• Re-ran the clean-computer workflow against the published CLI/action contract on 2026-07-27 and added explicit success, approval, verification, MCP, and failure checkpoints.
• Added the public clean-room CLI/MCP discovery, validation, planning, execution, and verification path on 2026-07-14.