CLI overview

This page is the front door to the platformctl reference. You will learn how to install the CLI, how it decides which endpoint to call and which credential to send, where its config file lives, and how it behaves when things go wrong.

What platformctl is

platformctl is the command-line tool for the Crusoe Agent Platform. It is one self-contained program written in Go — no runtime, no plugins. It packages a folder of agent code, uploads it, waits for the platform to build and start it, and then lets you chat with the agent, read its logs, set its secrets, and delete it. It also inspects the platform's managed services: serverless container services, pub/sub topics, memory stores, and vector indexes.

Almost everything the web console can do for agents and functions, platformctl can do in a scriptable form. Some platform administration areas (organizations, users, quotas, audit, service accounts, API keys, MCP servers) are console or API only — the platform and auth page lists them.

Install

Alpha

The platform is in alpha. There are no prebuilt binaries or package-manager installs yet. You build platformctl from a checkout of the platform source repository with a Go toolchain. Ask your administrator for repository access.

From the repository root:

( cd cli/platformctl && go build -o ../../bin/platformctl . )
export PATH="$PWD/bin:$PATH"
platformctl --help

The install guide walks through this step by step.

How the CLI reaches the platform

There is no public API hostname during the alpha. The web console at https://console.codyhill.dev is the public front door; the CLI reaches the API either through an endpoint your administrator gives you, or by opening its own tunnel into the cluster.

The CLI talks to two families of endpoints:

Control plane (most commands). The endpoint is resolved in this order:

1. The --api flag.
2. The $CAI_API environment variable.
3. Automatic port-forward: the CLI runs kubectl port-forward in the background against svc/agent-engine-api in the cai-system namespace, using the cluster in your KUBECONFIG. A port-forward is a temporary private tunnel from your machine into the cluster, so no public endpoint is needed.

Auto port-forward needs kubectl installed and a working KUBECONFIG. If it cannot connect, the command fails with:

auto port-forward failed (pass --api or set CAI_API instead): ...

Service groups (serverless, pubsub, memorystore, vectordb). These four command groups deliberately do not take their base URL from --api. Each has its own environment variable, and falls back to auto port-forwarding its own service in cai-system:

Command group	Env override	Port-forward target
platformctl serverless	CAI_SERVERLESS_API	svc/serverless-api in cai-system
platformctl pubsub	CAI_PUBSUB_API	svc/pubsub-api in cai-system
platformctl memorystore	CAI_MEMORYSTORE_API	svc/memorystore-api in cai-system
platformctl vectordb	CAI_VECTORDB_API	svc/vectordb-api in cai-system

--api is still used indirectly by these four groups: if --project is a slug or short name rather than a UUID, the CLI resolves it to a UUID through agent-engine-api, reached via --api, $CAI_API, or a port-forward. Pass the project's UUID to skip that call entirely.

Global flags

These flags work on every command.

Flag	Default	What it does
--api <url>	$CAI_API, else auto port-forward	Base URL of the control plane (agent-engine-api). The four service groups above do not take their base URL from it, but still use it to resolve a slug or short-name --project to a UUID.
--project <ref>	$CAI_PROJECT, else the saved default, else the server picks your single/default project	Which project to scope requests to. Accepts a project's slug, short id, or full UUID.
-o, --output <format>	table	Output format: table, json (pretty-printed), or yaml.
--json	off	Hidden legacy flag: emits one compact JSON line as the last line of stdout. Kept for existing scripts; use -o json instead.

Project resolution, most specific first: --project flag, then $CAI_PROJECT, then the default saved by platformctl config set-project, then empty (the server chooses). Note that $CAI_PROJECT beats the saved config default — the same convention as gcloud, aws, and az.

For control-plane commands (deploy, list, status, invoke, memorize, secrets, logs, delete, projects, and anything else that goes through agent-engine-api) the reference is sent as ?project=<ref> and resolved by the server, so a slug, short id, or UUID all cost the same — no extra API call.

The four service command groups (serverless, pubsub, memorystore, vectordb) are the exception: they need the project's UUID in the URL path, so a UUID is used directly with no extra API call (good for CI), while a slug or short name costs one lookup against GET /v1/projects.

Output formats and scripting

• -o table (default): human-readable columns.
• -o json: the full object(s), pretty-printed.
• -o yaml: the same, as YAML.
• --json (hidden, legacy): one compact JSON line as the last stdout line — the contract the platform's own e2e scripts rely on.

An invalid format fails with:

invalid --output "xml": want table, json, or yaml

Exit behavior and errors

• Commands exit 0 on success and non-zero on any failure, with the error printed to stderr.
• Any 4xx or 5xx from the API is wrapped as:

agent-engine-api returned <code>: <body>

• On a 401 or 403, the CLI also tells you which credential it tried:

agent-engine-api returned 401: ... [platformctl credential: none; run `platformctl login` or set $CAI_TOKEN]

The credential source shown is one of: none, $CAI_TOKEN, cached login (<path>), $CAI_USER/$CAI_PASSWORD, or automation token from secret/cai-automation-token.

Credential resolution

Every request carries at most one credential, sent as Authorization: Bearer <credential>. The CLI picks it in this order, most specific first:

1. $CAI_TOKEN — any bearer credential: a session token, or an API key in the format cai_<keyid>_<secret> (created under Security → API keys or service accounts in the console).
2. The cached login token written by platformctl login, stored at <UserConfigDir>/crusoe-ai/token (macOS: ~/Library/Application Support/crusoe-ai/token; fallback: $TMPDIR/crusoe-ai-token), owner-only permissions. Tokens last 12 hours; a token expiring within 30 seconds is treated as absent and the CLI falls through to the next source.
3. $CAI_USER + $CAI_PASSWORD — the CLI logs in on the spot via POST /v1/auth/login. It caches nothing, and on failure it falls through instead of erroring.
4. The automation token — a cluster Secret read via kubectl -n cai-agents get secret cai-automation-token. This is a cluster-admin convenience; it fails silently if kubectl, the cluster, or the Secret is absent.

Finding nothing is not an error. Invoking a deployed agent needs no credential by default (the "data plane" is open). Management commands — deploy, list, status, logs, secrets, delete — return a 401 annotated with the credential source that was tried. See API authentication for the full model.

The config file

platformctl config set-project saves your default project to:

<UserConfigDir>/crusoe-ai/config.json

The file has 0600 permissions (only you can read it) and contains {"default_project":"..."}. Remember: $CAI_PROJECT still overrides it. See the config commands for details.

Timeouts

Operation	Timeout
Any API request	5 minutes (deliberately generous for cold starts)
Deploy upload request	2 minutes
Deploy readiness polling	every 2 seconds, up to 5 minutes
Port-forward readiness	15 seconds
Automation-token kubectl read	15 seconds
logs --follow	none — tails until you stop it

How it compares

	platformctl	AWS CLI	gcloud	az
Install	Build from source (alpha)	Prebuilt installers and packages	Prebuilt installers	Prebuilt installers
Sign in	platformctl login, $CAI_TOKEN API keys	Access keys, SSO	Browser OAuth flow	Browser OAuth flow
Output	table, json, yaml	json, text, table	default, json, yaml, more	json, table, tsv, more
Coverage	Agents, functions, and read access to four data services	Hundreds of services	Hundreds of services	Hundreds of services

Honest summary: the big clouds' CLIs cover far more services and ship signed binaries. platformctl covers one platform, is built from source during the alpha, and several administration areas are console/API only. What it does cover, it covers end to end — deploy to invoke in two commands.

Pages in this section

• Agents and functions — deploy, functions deploy, list, status, invoke, memorize, secrets set, logs, delete, demo.
• Data and messaging — serverless, pubsub, memorystore, vectordb.
• Platform and auth — login, logout, whoami, projects list, config, and what is console/API only.