CLI (perpetual-ctl)

perpetual-ctl is the official CLI for the Perpetual Compute Orchestrator. It supports login (AWS Cognito), launch (with optional Docker image, command, and env vars), list, status, and recovery state—aligned with the web portal and API.

You must have an active AWS Marketplace subscription and complete registration before launching from the CLI. Use perpetual-ctl login to authenticate; the CLI stores tokens in ~/.perpetual/config.json.

Requirements: Python 3.9+.

From PyPI:

pip install perpetual-ctl

From source:

git clone https://github.com/perpetual-compute/perpetual-compute-cli.git
cd perpetual-compute-cli
pip install -e .

If plctl is not on your PATH after install, run plctl setup for instructions, or plctl setup --fix-path to add it to your shell config.

Summary of available commands:

• login — Authenticate with AWS Cognito (browser OAuth). Stores tokens locally.
• logout — Remove stored credentials.
• launch — Launch a Spot instance. Supports --instance-type, --image, --cmd, --env, --env-file (see Launch options).
• list — List your deployments (table or JSON).
• status — Show status of a deployment by instance ID.
• state — Get recovery URLs (manifest, checkpoint) for a deployment.
• logs — Not yet supported by the API.
• setup — Check PATH for plctl; optionally add scripts dir to shell rc (--fix-path).

The launch command accepts the same workload options as the web portal and API.

• --instance-type — AWS instance type (e.g. g6.xlarge, t3.micro). Overrides --gpu-type / --gpu-count.
• --image — Docker image URI for your workload (e.g. ECR URL). Optional.
• --cmd — Override container command (space-separated list). Optional.
• --env KEY=VALUE — Environment variable for the container. Can be repeated. Keys must match [A-Za-z_][A-Za-z0-9_]* and must not start with PERPETUAL_COMPUTE_ or AWS_.
• --env-file PATH — Path to a file with KEY=VALUE lines (one per line). Optional.
• --region — AWS region (e.g. us-east-1). Optional; auto-selects cheapest if omitted.
• --dry-run — Preview cost from API without launching.

Example with Docker image and env:

perpetual-ctl launch --instance-type g6.xlarge \
  --image 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-job:latest \
  --env S3_OUTPUT=s3://my-bucket/outputs \
  --env-file .env.workload \
  --cmd python train.py --epochs 10

Without --instance-type, the CLI maps --gpu-type and --gpu-count to an AWS instance type (e.g. a100 × 2 → g6.2xlarge). Allowed GPU types: a100, h100, v100, t4.

To use a specific instance type (e.g. t3.micro for testing), pass --instance-type t3.micro. Allowed types are defined by the orchestrator (e.g. g6.xlarge, g6.2xlarge, g6.48xlarge, p5.48xlarge, p4d.24xlarge, t3.micro, t3.small, t3.medium).

Use perpetual-ctl state <instance_id> to get pre-signed URLs for the latest checkpoint and manifest (same as the “Recover data” flow in the portal). The response includes manifest_url, optional checkpoint_url, and expires_in_seconds.

If your deployment is customer-scoped (Marketplace), the CLI sends your stored customer_identifier so the API can authorize the request.

When not set, Cognito and API config are loaded automatically from api.perpetualcompute.com (cached 24h). Override for staging or air-gapped use:

• PERPETUAL_API_URL — API base URL (default: https://api.perpetualcompute.com)
• PERPETUAL_COGNITO_DOMAIN — Cognito hosted UI domain
• PERPETUAL_COGNITO_CLIENT_ID — Cognito app client ID
• PERPETUAL_COGNITO_REGION — Cognito region (default: us-east-1)
• PERPETUAL_REDIRECT_PORT — Local port for OAuth callback (default: 9876)