Skip to main content

Install the CLI

platformctl is the official command-line interface for the Crusoe AI Platform. It allows you to package and deploy agents, serverless functions, and container workloads, interact with deployed agents, manage secrets, inspect logs, and configure project settings directly from your terminal or CI/CD pipelines.

Installation​

Choose the installation method that fits your operating system and environment:

Run the installer in your terminal:

curl -fsSL https://www.codyhill.net/install.sh | sh

It detects your system, downloads the matching build, checks it against the published SHA-256 checksum, installs it, and saves your platform's API address so the next command you run already knows where to go. If no checksum tool is available it stops rather than install something it could not verify.

It installs to /usr/local/bin when that directory is writable and to ~/.local/bin otherwise, and tells you which. It never runs sudo on your behalf. To choose somewhere else:

curl -fsSL https://www.codyhill.net/install.sh | PLATFORMCTL_INSTALL_DIR="$HOME/bin" sh

Verify the installation:

platformctl --help

You should see the list of available command groups (login, deploy, invoke, list, logs, secrets, and more).

Endpoint Configuration​

platformctl needs to know your platform's API address once. It is api. on your platform's domain; save it:

platformctl config set-api https://api.codyhill.net

The installer saves this for you, so you only need the command above after a direct download or a build from source. platformctl config view shows the file it was written to and what is in it. To point one shell or one command somewhere else - a staging platform, a private endpoint - set the CAI_API environment variable or pass the --api flag; both override the saved address:

export CAI_API=https://api.codyhill.net

You can also specify service-specific overrides when using private endpoints:

  • CAI_SERVERLESS_API
  • CAI_PUBSUB_API
  • CAI_MEMORYSTORE_API
  • CAI_VECTORDB_API
  • CAI_GATEWAY_API
  • CAI_INFERENCE_API

Authentication​

Sign in to your platform account using your credentials:

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

Upon successful authentication, platformctl writes the session token to your user configuration directory (e.g., ~/.config/crusoe-ai/token or ~/Library/Application Support/crusoe-ai/token). The token is stored as plain text, protected by file permissions only: the file is 0600 inside a 0700 directory. It is a bearer credential — anyone who can read that file can act as you until it expires. If the CLI cannot determine a user config directory, it falls back to $TMPDIR/crusoe-ai-token, which on a shared host is a worse place for it; set XDG_CONFIG_HOME rather than accept the fallback. Session tokens remain valid for 12 hours.

Verify your active identity at any time:

platformctl whoami

Output:

user@example.com  role=user  (credential: cached login)

To sign out and clear your cached credentials:

platformctl logout

Setting Default Scope​

Most platformctl operations run within the context of a specific Project. List your available projects and set a default:

platformctl projects list

Output:

SLUG      NAME      SHORT   ROLE    ID
ml-team   ML Team   ab12cd  member  1f2e3d4c-5678-90ab-cdef-1234567890ab

Set your active default project by slug or short ID:

platformctl config set-project ml-team

The CLI checks scope in the following order of precedence:

  1. Explicit --project flag
  2. CAI_PROJECT environment variable
  3. Saved default project setting

Output Formats​

platformctl supports multiple output formats for easy terminal reading or automated scripting:

# Default table output
platformctl projects list

# JSON format for jq parsing
platformctl projects list -o json

# YAML format
platformctl projects list -o yaml

Next Steps​