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 automated installer script in your terminal:

curl -fsSL https://cli.codyhill.dev/install.sh | bash

The script automatically detects your OS and architecture, downloads the latest platformctl release, and installs it to /usr/local/bin.

Verify the installation:

platformctl --help

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

Endpoint Configuration​

By default, platformctl automatically connects to the public Crusoe AI Platform API at https://api.codyhill.dev.

If you need to direct traffic to a custom API gateway or private staging environment, set the CAI_API environment variable or pass the --api flag:

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

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​