CLI package

Use @topolo/cli for Topolo tasks from a terminal or an agent that drives command-line tools. This guide covers CLI 0.13.13, which bundles MCP 0.14.27 and SDK 0.23.22. The guide is a versioned reference dated 15 October 2026. Newer package releases and a local installation's active version must be considered separately. [C1, C2]

Establish the workstation and identity

Node.js 20 or newer is required. For an installation approved to use this version:

npm install -g @topolo/cli@0.13.13
topolo --version
topolo auth status --json
topolo whoami --json

These commands are illustrative and unexecuted. Install and authentication operations can change local state or contact Topolo; use an existing managed profile only under its owner's authority. For a new interactive credential, topolo auth login uses the documented device approval flow. Keep credential values in the supported protected source rather than a command example, project file, or log. [C1, C3]

The credential fixes the personal or organization context. Discover stored choices with topolo context ls --json. Interactive topolo context use changes the active CLI context and mints a credential; concurrent automation should pin an existing exact context instead of racing that shared selection. Do not combine a stored-context pin with an injected credential. There is no ordinary --org override for an action request. [C1, C3]

Find the application and resource

Use the credential-scoped catalogs rather than an assumed service name:

topolo apps --json
topolo apps get '<discovered application>' --json
topolo resources '<discovered application>' --json
topolo workspaces list '<discovered application>' --json

Replace every angle-bracket placeholder with an actual returned value. A workspace is an app-specific resource, not an organization ID. Read data.policy.canCreate and data.policy.reason before considering workspace creation. Organization ownership does not grant every app's workspace permission. The application directory is live and credential-scoped; it is not a complete platform or repository inventory. [C1, C3]

Discover and inspect the action

topolo actions --service '<discovered application>' --query '<task keyword>' --limit 25 --json
topolo actions capabilities --service '<discovered application>' --json
topolo actions get '<returned action ID>' --json
topolo actions examples '<returned action ID>' --json

Inspect the full input and output schemas when compact guidance is insufficient. Check required permissions, resource binding, effect descriptions, examples, verification, and recovery. A runtime-authorized action may be discoverable before the target service decides whether this request is allowed. Resolve an example's missing identifiers before using it; an omitted example input does not authorize {}. [C3]

Validate and plan concrete input

Put one schema-valid JSON object in payload.json. The @ syntax reads the UTF-8 file and avoids putting a large JSON payload on the command line:

topolo actions validate '<returned action ID>' --data @payload.json --json
topolo actions plan '<returned action ID>' --data @payload.json --json

Planning does not perform the requested action. Before an approved mutation, include --confirm in the plan so it reflects the confirmed request. A missing confirmation and an invalid schema are different blockers. Do not treat an invalid or otherwise non-executable plan as permission to call the action. [C3]

When the discovered action requires resource context, add both --resource-type and --resource-id to its plan and call, using the published resource type and discovered identifier. Keep them separate from the action's JSON data and from the organization context. Use exactly the same input and resource for the approved call. [C1, C3]

Execute and verify the authorized task

For an automatic read, use topolo actions call with its exact published input and resource flags. For an already authorized mutation, add --confirm. Confirmation is a transport safeguard; permissions and the user's authorization still apply. Follow the action's verification steps immediately and read the exact affected record, version, or job. If verification fails, preserve the request and result before considering a supported recovery. [C3]

topolo actions upload requires a published upload contract. Its file, content type, size limits, and URL-session completion mapping come from that contract. topolo api is an escape hatch only for a fully documented endpoint; missing action discovery does not authorize guessing a private path. Never invent a rollback endpoint. [C1, C3]

Register the bundled MCP for an agent host

topolo setup --name topolo-example --context '<discovered context key>' --env production
topolo doctor --name topolo-example

setup registers the exact local MCP resolved from this CLI's dependency graph. Install and synchronize the CLI cohort rather than separately assembling MCP and SDK versions. A named context registration keeps concurrent agents from changing a shared active selection. doctor checks authentication, handshake, discovery, and identity. Those checks do not establish that an agent completed a particular Topolo task. [C1, C3]

Understand the agent pack boundary in 0.13.13

topolo agent-packs is the bundled entry point for portable business agent packs. Local pack operations require Python 3.11 or newer and a supported native host. For example, the published interface includes topolo agent-packs status and topolo agent-packs open --adapter-help. First add builds an installed instance; later add and switch operations resume it. Host configuration, cloud connection, and task completion have separate requirements. [C1, C4]

Cloud connection requires explicit environment and authenticated context, discovered Agent and Bytes workspaces, and a roles.json mapping to existing published agentId and agentVersionId values. The CLI does not create grants or silently publish agent versions. A selected private profile reference is metadata for a connection, not proof of native MCP configuration or runtime health. [C1, C4]

In this exact release, dynamic private Claude startup refuses with native_private_query_prestart_contract_unqualified. A selected private profile does not lift that boundary. The native-cli continuity transport can describe a plan, but its native effects refuse with native_cli_startup_unqualified before client, helper, or native access. Version 1 plans remain readable and do not silently become version 2 CLI plans. Source fixtures, installed files, and an external shell identity receipt do not establish native thread context or task completion. [C1, C4]

These are documented limits of 0.13.13. Its shipped native CLI admission function still refuses because supported startup, profile-refresh authority and native-result producers are unavailable. Supplied hashes, flags or evidence references do not provide those producers. Do not substitute behavior from another version to make a refused operation proceed. [C7]

Prepare private runtime configuration

CLI 0.13.12 introduced agent-packs runtime-adoption plan|apply with the legacy consumer tuple. Driver 0.13.13 retains that tuple and adds the complete CLI 0.13.12/MCP 0.14.27/SDK 0.23.22 consumer tuple. It forwards the operation to the bundled successor Python adapter. Planning is nonwriting; apply is one configuration-only attempt, not a consumer startup or authentication check. [C1, C4, C5, C8]

Illustrative commands, to be used only with a complete owner-reviewed manifest and existing configuration-change authority:

topolo agent-packs --store /owned/AgentPacks runtime-adoption plan --manifest /review/adoption.json
topolo agent-packs --store /owned/AgentPacks runtime-adoption apply --manifest /review/adoption.json --plan-digest '<reviewed SHA256>' --confirm

The manifest's closed fields are schemaVersion, operationId, library, ownerGeneration, consumers, profile, runtime, targets, launcher, and preserve. It binds the complete existing consumer set, every effective physical transport configuration, shared aliases, exact file preimages, private-profile metadata, and preservation records. Each server in a targeted physical configuration must be either a targeted transport or explicitly untouched. Empty or incomplete manifests refuse. The reviewed plan digest must match the exact apply input. [C4, C5]

Two version sets have different purposes:

Choose one complete accepted consumer tuple. Versions cannot be mixed between rows, and consumer CLI 0.13.13 is not accepted by this validator. The driver's version and its own dependencies do not select or prove the consumer tuple. The validator also checks package and entry pins, each consumer CLI/MCP package's exact SDK dependency, and the separately pinned successor Python adapter files. Configuration preparation does not establish that a running consumer loaded the selected cohort. [C2, C4, C5]

Apply preserves existing physical aliases and controlled settings, records verified replacements in an exclusive operation journal, and reports configuration-prepared-native-adoption-unverified only after its readbacks. It does not install skills, rebind a home, replace existing instructions or permissions, start a consumer, or probe Auth. A conflict or interruption retains the journal and uncertain files for owner reconciliation; there is no automatic replay or rollback. [C4, C5]

Later startup may contact private Auth and renew the selected profile, so it needs its own current owner authorization and permission, identity, context and outcome evidence. Existing refusals and scoped holds remain applicable. A successful configuration apply is not native reload, profile health, a granted permission, or a completed Codex or Claude task. [C4]

Handle the updated sign-in and rate-limit behavior

The SDK 0.23.22 code bundled with this CLI distinguishes reauth_required from transient renewal errors and exposes typed rate-limit behavior. A terminal saved-grant refusal can initiate a shared device-approval flow; an Auth 429 retains the saved grant. Use supported prompt fields and the approved profile workflow rather than printing a raw configuration or repeatedly sending the refused grant. The exact CLI error wrapper and transport remain authoritative; do not assume every SDK helper is a new CLI command. [C6]

Service 429 backoff in the bundled client is restricted to GET and HEAD, with at most two rate-limit retries when the wait is at most ten seconds. It is not permission to replay an uncertain mutation or to override a profile hold. The CLI's protocol SDK pin is 1.31.0 and its doctor uses stdio; that fact does not prove migration of separate HTTP OAuth consumers or live native adoption. [C2, C6]

Interpret failures and retain the request identity

When JSON output provides an error code, branch on that code rather than matching message prose. Preserve the sanitized request ID for diagnosis. A timeout after a possible write is an uncertain outcome; reconcile it before replay. A retry interval does not authorize a new login, a held operation, broader permissions, or duplicate publication. [C1, C3]

Sources for this version

[C1] Published CLI 0.13.13 archive, member package/README.md.

[C2] The same archive, member package/package.json.

[C3] The same archive, member package/skills/topolo/SKILL.md.

[C4] The same archive, member package/agent-packs/README.md, including Private runtime adoption.

[C5] The same archive, members package/agent-packs/src/topolo_agent_pack/live.py and package/agent-packs/src/topolo_agent_pack/cli.py, plus package/dist/index.js for CLI forwarding.

[C6] The same archive, member package/dist/index.js, and SDK 0.23.22 archive, members package/dist/index.js and package/dist/node/credential-store.js. All commands remain illustrative and unexecuted.

[C7] The CLI 0.13.13 archive, member package/agent-packs/src/topolo_agent_pack/lanes.py, function native_cli_admission.

[C8] CLI 0.13.12 archive, member package/agent-packs/src/topolo_agent_pack/live.py, for the preceding legacy-only consumer tuple.