command-reference.md

PCL command reference

PCL uses a resource-first grammar:

pcl [global options] <resource> <operation> [arguments] [options]

Run pcl, or any resource name such as pcl vm, to print help and exit successfully. Run pcl <path> --help for detailed behavior, safety notes, and copyable examples. Misspelled commands return exit code 2 and suggest the closest known command.

For a machine-readable contract, use:

pcl describe --compact --format json
pcl describe vm create --format json

The compact form is intended for discovery. Inspect a specific path before constructing a command; the full result includes arguments, options, aliases, safety class, authentication and confirmation requirements, notes, and examples.

Global options

Global options may appear before or after a subcommand.

Option	Meaning
--profile <name>	Use a profile without changing the stored active profile.
--format <mode>	auto, json, table, yaml, or plain.
--no-color	Disable ANSI color. NO_COLOR has the same effect.
--verbose	Write request diagnostics to stderr with secrets redacted.
--quiet	Suppress progress and human success noise, not primary output.
--api-base <url>	Override the API base. HTTPS is required except for localhost development.
--timeout-ms <ms>	Set a positive request timeout in milliseconds.
--version	Print the version and exit.
--help	Print help and exit.

Precedence is explicit CLI option, environment variable, profile/config value, then built-in default.

Authentication and local configuration

Command	Description	Example
pcl login [token]	Validate and store a token. A hidden prompt is safest; --token-stdin is intended for automation.	pcl login --profile production
pcl logout	Remove the selected profile credential from all applicable secure stores. It cannot unset PCL_TOKEN in the parent shell.	pcl logout --profile production
pcl whoami	Validate the resolved credential and show the authenticated identity and credential source.	pcl whoami --format json
pcl auth migrate	Move legacy plaintext credentials into the keychain or passphrase-protected encrypted storage. Plaintext is deleted only after verification.	pcl auth migrate --profile production
pcl doctor	Check configuration, credential resolution, and API reachability. It always prints a report; failed checks return 1.	pcl doctor --format json
pcl version	Print build/version information.	pcl version --format json

Credential precedence is PCL_TOKEN, OS keychain, then encrypted profile storage. Encrypted storage requires PCL_TOKEN_PASSPHRASE or a secure TTY prompt. PCL never stores plaintext tokens in configuration files.

Profiles

Command	Description	Example
pcl profile list	List profiles and mark the active one. Alias: ls.	pcl profiles ls --format json
pcl profile use <name>	Change the stored active profile. Alias: switch.	pcl profile switch staging
pcl profile create <name>	Create profile metadata without fabricating a credential. Log in separately to store a token.	pcl profile create production
pcl profile delete <name>	Delete profile metadata and its stored credential. Interactive confirmation is required unless --yes is used.	pcl profile delete old-profile --yes
pcl profile show [name]	Show the named profile, or the resolved active profile when omitted.	pcl profile show production --format json

Configuration

Command	Description	Example
pcl config get <key>	Read a supported config value.	pcl config get format_default --format json
pcl config set <key> <value>	Validate and persist a supported config value.	pcl config set color never
pcl config unset <key>	Remove a stored override so normal fallback precedence applies.	pcl config unset color
pcl config path	Print the active config directory/path.	pcl config path --format json
pcl config reset	Reset local configuration. Interactive confirmation is required unless --yes is used.	pcl config reset --yes

Virtual machines

VM references resolve in this order: exact ID, exact name, unique case-insensitive name. Ambiguous names are listed and no mutation is sent.

Command	Description	Example
pcl vm list	List VMs. Perspective data is the default; --basic requests the smaller base representation.	pcl vm list --columns id,name,status,ip_addr
pcl vm get <vm>	Get one VM by safe reference resolution. Alias: show.	pcl vm show coolify --format json
pcl vm create	Request full provisioning. RAM is GB; image and compute pool are required unless --draft-only is explicit.	pcl vm create --name web-01 --ram 4 --image <image-id> --compute-pool <pool-id> --wait
pcl vm export <vm> [file]	Export reusable create settings as a versioned, secret-free JSON template.	pcl vm export coolify --file coolify.pcl-vm.json
pcl vm import <file>	Validate a PCL VM template and create exactly one VM; CLI options override template values.	pcl vm import coolify.pcl-vm.json --name coolify-staging --wait
pcl vm start <vm>	Resolve and invoke the documented start action. Refuses when the live catalog has no valid start action.	pcl vm start coolify
pcl vm stop <vm>	Stop a VM after confirmation.	pcl vm stop coolify --yes
pcl vm restart <vm>	Restart a VM after confirmation.	pcl vm restart coolify --yes --format json
pcl vm reboot <vm>	Invoke the reboot alias after confirmation.	pcl vm reboot coolify --yes
pcl vm delete <vm>	Delete a VM after confirmation. An uncertain result never triggers an implicit start or recovery mutation.	pcl vm delete coolify --yes
pcl vm console <vm>	Request console access. Treat the result as sensitive because it may contain short-lived access material.	pcl vm console coolify
pcl vm ssh <vm>	Open SSH using a VM address or explicit host. Interactive mode remains interactive.	pcl vm ssh coolify --address private --user deploy
pcl vm wait <vm>	Poll until the VM reaches a terminal/desired provisioning state or times out.	pcl vm wait coolify --timeout 600 --interval 5
pcl vm ops <vm>	Show current, available, or blocked operations for a VM.	pcl vm ops coolify --show-current --show-blocked --format json
pcl vm actions	List the live VM action catalog.	pcl vm actions --format json
pcl vm do <vm> [action]	With no action, show valid actions for the VM. With an action, resolve its UUID and send exactly one request.	pcl vm do coolify restart --yes
pcl vm action <vm> <action-name>	Compatibility spelling for pcl vm do.	pcl vm action coolify restart --yes

Natural resource aliases are vm, vms, server, and servers. Unknown actions are refused. --experimental selects the isolated undocumented name-based route directly; it is not an automatic fallback. --fallback is explicit and reports the selected route. Do not use either flag speculatively.

Exporting and importing VM settings

This is configuration cloning, not disk cloning:

# Read one VM and write a portable template.
pcl vm export coolify --file coolify.pcl-vm.json

# Validate locally. No token and no API call are required.
pcl vm import coolify.pcl-vm.json --dry-run --format json

# Create using the suggested <source-name>-copy name.
pcl vm import coolify.pcl-vm.json --wait

# Override selected template values without editing the file.
pcl vm import coolify.pcl-vm.json --name coolify-staging --ram 8 --compute-pool <pool-id>

The template contains only fields accepted by the current documented VM-create contract: name, RAM, compute-pool ID, repository-image ID, description, common-domain ID, object-form tags, and automatic-backup interval. PCL excludes:

• passwords, credentials, API tokens, and VM tokens;
• post-boot script/user-data;
• disk contents, snapshots, IP addresses, and network attachments;
• runtime state, pending operations, and CPU count.

Use --user-data <file> during import when a new post-boot script is required. Existing export files are not replaced unless --force is explicit. Templates are limited to 1 MiB, must be UTF-8 JSON, carry kind: plusclouds.vm-template and version: 1, and reject unknown spec fields rather than silently ignoring typos. Import performs one create call and never automatically replays an ambiguous failure.

The live API stores VM RAM in GB. PCL therefore treats --ram 4 as 4 GB, not 4096 MB. Full provisioning refuses a missing image or compute-pool reference. Use --draft-only only when a non-bootable database draft is intentional; it cannot be combined with --wait. When a full create times out, PCL reads the VM perspective and emits disk_count, total_disk_size, and network-card count. likely_cause: backend-provisioning-not-started means the request was accepted but no first disk appeared; agents must inspect state rather than replaying it.

SSH defaults to the user's OpenSSH host-key policy. BatchMode=yes is applied only with --cmd or --batch. User resolution is --user, PCL_SSH_USER, VM metadata, then root; an explicit user@host wins.

pcl vm ssh coolify
pcl vm ssh coolify --cmd "systemctl status coolify" --batch
pcl vm ssh coolify --host deploy@example.com
pcl vm ssh coolify --host-key-policy accept-new

Images and compute pools

These are read-only discovery resources used when constructing VM creates.

Command	Description	Example
pcl image list	List OS images/templates; filter with --os and select columns as needed.	pcl image list --os ubuntu --format json
pcl image get <id>	Get one image. Alias: show.	pcl images show <image-id> --format json
pcl compute-pool list	List compute pools and their capacity fields. Aliases: pool, pools.	pcl pool list --columns id,name,cpu,ram
pcl compute-pool get <id>	Get one compute pool. Alias: show.	pcl pool show <pool-id> --format json

Networks

Command	Description	Example
pcl network list	List virtual networks.	pcl networks list --format json
pcl network get <id>	Get one virtual network. Alias: show.	pcl network show <network-id>
pcl network create	Create a virtual network using a network pool, cloud node, and optional CIDR.	pcl network create --name private --network-pool <pool-id> --cloud-node <node-id> --cidr 10.0.0.0/24
pcl network delete <id>	Delete a virtual network after confirmation.	pcl network delete <network-id> --yes

Storage volumes

Command	Description	Example
pcl storage list	List volumes through the documented storage-volume endpoint.	pcl volumes list --format json
pcl storage get <id>	Get one volume. Alias: show.	pcl volume show <volume-id>
pcl storage create	Create a volume in a storage pool.	pcl storage create --name data --size 100 --type ssd --storage-pool <pool-id>
pcl storage resize <id>	Increase volume size after confirmation.	pcl storage resize <volume-id> --size 200 --yes
pcl storage delete <id>	Delete a volume after confirmation.	pcl storage delete <volume-id> --yes
pcl storage attach <id>	Attach a volume to a VM using the documented action catalog.	pcl storage attach <volume-id> --vm <vm-id>
pcl storage detach <id>	Detach a volume from a VM after confirmation.	pcl storage detach <volume-id> --vm <vm-id> --yes

The documented storage-volume routes returned HTTP 404 for the tested account in the latest authenticated read-only probe. PCL surfaces that result and does not substitute non-equivalent VM disk-agent or storage-association routes.

IP addresses

Command	Description	Example
pcl ip list	List managed IP addresses.	pcl ips list --format json
pcl ip get <id>	Get one IP address. Alias: show.	pcl ip show <ip-id>
pcl ip allocate	Allocate/register an address on a network. Alias: create.	pcl ip create --address 203.0.113.10 --network <network-id>
pcl ip release <id>	Release an address after confirmation. Alias: delete.	pcl ip delete <ip-id> --yes
pcl ip attach <id>	Attach an address to a VM through the documented action catalog.	pcl ip attach <ip-id> --vm <vm-id>
pcl ip detach <id>	Detach an address from a VM after confirmation.	pcl ip detach <ip-id> --vm <vm-id> --yes

Datacenters and regions

Command	Description	Example
pcl datacenter list	List documented datacenters. Aliases: dc, datacenters.	pcl dc list --format json
pcl datacenter get <id>	Get one datacenter. Alias: show.	pcl dc show <datacenter-id>
pcl region list	Call the isolated region compatibility route. Requires --experimental.	pcl region list --experimental --format json
pcl region get <id>	Get one region through the compatibility route. Requires --experimental; alias: show.	pcl region show <region-id> --experimental

The region route is not in the current official catalog and returned HTTP 403 in the latest probe. That evidence does not justify automatic fallback.

Output and automation contract

• auto uses a table on an interactive terminal and JSON when stdout is not a terminal.
• Explicit json, yaml, and plain are stable machine modes.
• Primary data goes to stdout. Diagnostics, progress, warnings, and verbose traces go to stderr.
• --quiet does not hide primary data.
• Destructive commands prompt on a TTY and refuse noninteractive execution without --yes or the command's documented confirmation option.
• Read requests may retry retryable failures. Mutations are not retried after an ambiguous transport, timeout, malformed response, or 5xx result.

Exit codes

Code	Meaning	Automation response
0	Success	Consume stdout.
1	Generic failure or failed doctor check	Inspect structured error/report.
2	Usage, validation, or missing confirmation	Correct the invocation; do not retry unchanged.
3	Authentication failure	Refresh or select credentials.
4	Not found or permission failure	Verify identity, resource ID, and authorization.
5	Conflict	Refresh state before deciding.
6	Rate limited	Honor retry guidance and back off.
7	Transport failure	Reads may be retried; inspect mutation safety first.
8	Server failure	Retry reads conservatively; do not replay mutations automatically.
9	Unknown mutation outcome	Inspect resource state; never replay automatically.

For agent-specific discovery and safety rules, see llm-usage.md. Endpoint behavior follows the official PlusClouds API documentation; recorded compatibility evidence is isolated in compatibility.md.