Topolo Docs Topolo Platform
Open workspace

Quick Start

Fast onboarding path for developers integrating with Topolo services.

Connect Topolo

You need Node.js 20 or newer and a Topolo account or authorized API key. Install the public CLI and sign in:

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

Complete the browser authorization flow. Check that whoami identifies the person and organization intended for this work. For a headless process, supply an authorized API key through your secret manager as TOPOLO_API_KEY; keep it out of source files and command transcripts.

Set up your agent host

topolo setup
topolo doctor

Setup installs the skill and the exact MCP server bundled with the CLI for supported local hosts. Doctor checks the credential and MCP connection. Restart your agent host after setup so it loads the new tools.

Choose the right context

topolo context ls --json

For interactive work, select an exact returned context using topolo context use <context> --json, then check whoami again. For automation, pin TOPOLO_CONTEXT to the exact returned key for each process; do not change a shared active context while other agents are operating. See Agents and automation for named MCP connections. Do not combine a context pin with an injected API key: the key already fixes its context.

Discover a safe first read

topolo apps --json
topolo actions --service topolo-docs --limit 100 --json
topolo actions get app_topolo_docs.public_machine.index --detail --json
topolo actions examples app_topolo_docs.public_machine.index --json

This action reads the public documentation index. It changes no document. Read its input schema, effects and verification instructions before continuing. Save this exact JSON object as payload.json:

{
  "spaceSlug": "topolo-platform"
}

Validate and plan it:

topolo actions validate app_topolo_docs.public_machine.index --data @payload.json --json
topolo actions plan app_topolo_docs.public_machine.index --data @payload.json --json

Proceed only when validation succeeds and the plan is executable. Execute the unchanged read:

topolo actions call app_topolo_docs.public_machine.index --data @payload.json --json

The action returns formatVersion, spaceSlug, documents and actions. Each document entry includes its document and version identifiers, title, human URL and machine URL. Follow one returned machine URL and compare its version identifier with the index entry. Document counts and identifiers can change as new versions are published. The full action guide contains captured examples and error recovery.

Use the same workflow in MCP

Use topolo_whoami, topolo_search_applications, topolo_search_actions and topolo_get_action. Prepare the selected input with topolo_prepare_action, or validate and plan separately with topolo_validate_action and topolo_plan_action. Execute this automatic read with topolo_read_action.

For a mutation, review the exact request, input, resource context, effects and recovery, then obtain approval unless the user already authorized that concrete work. Use topolo_call_action with confirm: true only after authorization. Perform every published verification step after the call.

Recover from a failed step

  • Authentication failure: sign in again, then repeat identity and discovery.
  • Missing application or action: verify context and repeat bounded discovery.
  • Invalid input: correct only the schema errors reported for that input.
  • Confirmation required: obtain authorization for the reviewed mutation.
  • Runtime denial: preserve the error and request identifier; do not widen access or substitute guessed fields.
  • Missing instructions or examples: report the gap and stop the affected operation.