Skip to main content

Install the CLI

platformctl is the platform's command-line tool. It packages and deploys your agent or function code, lets you chat with deployed agents, reads logs, sets secrets, and inspects the platform's managed services — everything the web console does for those workloads, in scriptable form. This page gets it built, signed in, and pointed at your project.

Before you begin​

  • A platform account — see Create an account.
  • A Go toolchain installed (go on your PATH). platformctl is a single Go binary.
  • Access to the platform source repository — ask your administrator.
Alpha honesty

There are no prebuilt downloads of platformctl yet — during alpha you build it from the platform repository yourself. It compiles in seconds and has no runtime dependencies.

1. Build the binary​

From the root of the platform repository:

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

Check it runs:

platformctl --help

You should see: the command list (login, deploy, invoke, list, logs, and more). The full command tree is in the CLI reference.

2. Tell it where the API is​

There is no public API hostname during alpha, so platformctl resolves its endpoint in this order:

  1. The --api flag on any command.
  2. The CAI_API environment variable.
  3. Automatic port-forward: if neither is set, the CLI opens a background kubectl port-forward tunnel to the platform using the cluster in your KUBECONFIG.

If your administrator gave you an API endpoint, set it once per shell:

export CAI_API=https://your-admin-provided-endpoint

If you have cluster credentials instead, set nothing — the CLI tunnels in by itself. If it can't, you'll see:

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

That means you need either a working KUBECONFIG or a CAI_API value from your admin.

3. Sign in​

platformctl login --email you@example.com --password 'your-password'

You should see:

signed in as you@example.com; token cached

The session token is cached in your user config directory with owner-only file permissions (on macOS: ~/Library/Application Support/crusoe-ai/token). Tokens last 12 hours; after that, log in again.

Confirm who you are:

platformctl whoami

You should see:

you@example.com  role=user  (credential: cached login (~/Library/Application Support/crusoe-ai/token))

The credential: note tells you which credential source the CLI is actually using — useful when an environment variable is silently winning. The CLI checks these in order, most specific first:

  1. $CAI_TOKEN — an API key or session token. Beats everything.
  2. The cached login token from platformctl login.
  3. $CAI_USER + $CAI_PASSWORD — logs in on the spot, caches nothing.
  4. The platform automation token, read from the cluster (admins only).

To sign out:

platformctl logout

You should see:

cached token discarded (note: $CAI_TOKEN and the automation token, if present, still apply)
Invoking works without signing in

Talking to a deployed agent (platformctl invoke) needs no credential by default. Managing things — deploy, logs, secrets, delete — always does. See Core concepts for why.

4. Set your default project​

Most commands need to know which project you mean. Look up yours, then save it as the default:

platformctl projects list

You should see:

SLUG      NAME      SHORT   ROLE    ID
ml-team   ML Team   ab12cd  member  1f2e3d4c-...
platformctl config set-project ml-team

You should see:

default project set to ml-team

Project resolution order on every command: the --project flag, then $CAI_PROJECT, then this saved default, then the server picks your single or default project. You can pass a project by slug, short id, or UUID.

5. Pick an output format​

Every command takes -o/--output:

FormatWhat you get
table (default)Human-readable columns
jsonPretty-printed JSON — pipe it to jq
yamlYAML
platformctl projects list -o json

An invalid value fails with:

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

You may also see a --json flag in older scripts — it's a hidden legacy flag that prints one compact JSON line. Prefer -o json for new work.

Next steps​