pcl — PlusClouds CLI

pcl manages PlusClouds infrastructure through the documented API at https://api.plusclouds.com.

The endpoint contract comes from the official PlusClouds API documentation. Undocumented compatibility behavior is isolated in docs/compatibility.md.

Development quick start

pnpm install
pnpm build
node dist/cli.js --version

Finding commands

Running PCL or a resource group with no operation prints help and exits successfully. Command help includes behavior, safety notes, and copyable examples. Typos return a usage error and suggest the nearest known command.

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

pcl describe is the stable machine-readable command contract. Its full JSON form includes arguments, options, global options, aliases, authentication and confirmation requirements, safety class, notes, and examples. LLMs should use the compact catalog for discovery and then inspect the exact command before execution.

See the complete command reference and the LLM/automation guide.

Authentication

Interactive login uses a hidden prompt:

node dist/cli.js login

For automation, avoid command-line token arguments and shell history:

Get-Content .token | node dist/cli.js login --token-stdin
$env:PCL_TOKEN = "..."  # highest-priority one-off credential
node dist/cli.js vm list

Credential precedence is:

1. PCL_TOKEN
2. the active profile in the OS keychain
3. the active profile in AES-256-GCM encrypted-file storage

The keychain is preferred. If its OS service fails at operation time, encrypted-file storage requires a user-controlled passphrase from PCL_TOKEN_PASSPHRASE or a hidden TTY prompt. Existing encrypted credentials remain readable if the keychain later becomes available. A successful keychain write removes a stale encrypted copy. Logout checks both stores and reports an error if deletion cannot be completed; it cannot unset an active PCL_TOKEN override. Noninteractive encrypted access without a passphrase fails. Tokens are never written to plaintext config files.

pcl whoami
pcl logout
pcl profile list
pcl profile use staging
pcl auth migrate

Natural VM commands

VM references are resolved by exact ID, exact name, then a unique case-insensitive name. Prefixes are suggestions only and never authorize a mutation.

pcl vm list
pcl vm show coolify
pcl vm do coolify restart
pcl vm stop coolify --yes
pcl vm delete coolify --yes

Natural aliases include server/servers for vm, show for resource get, volume/volumes for storage, and dc for datacenter. Canonical command paths remain stable for scripts.

pcl vm action remains a compatibility alias for pcl vm do. Named actions are resolved through GET /iaas/virtual-machines/actions, and the returned action UUID is sent once through the documented POST /iaas/virtual-machines/{vmId}/do/{actionId} route. Unknown names are refused. Catalog actions other than start require confirmation; unclassified actions are treated conservatively. --experimental selects the isolated name-based compatibility route directly; it is never an automatic fallback.

Mutations are never retried. A timeout, transport error, malformed/oversized response, or 5xx after a mutation returns an unknown_outcome error and requires inspection before manual recovery. HTTP request and response bodies are capped at 10 MiB before transmission or parsing.

Export and import VM settings

pcl vm export coolify --file coolify.pcl-vm.json
pcl vm import coolify.pcl-vm.json --dry-run --format json
pcl vm import coolify.pcl-vm.json --name coolify-staging --wait

Export/import copies reusable VM-create settings, not disks or snapshots. The template excludes credentials, tokens, user-data, disk contents, IP/network attachments, and runtime state. Export suggests <source-name>-copy; import options override template values. --dry-run validates locally without a token or API call. See the VM template contract.

Create commands

The required fields follow the current documented schemas:

pcl vm create --name web-01 --ram 4 --image <image-id> --compute-pool <pool-id>
pcl network create --name private --network-pool <pool-id> --cloud-node <node-id> --cidr 10.0.0.0/24
pcl storage create --name data --size 100 --type ssd --storage-pool <pool-id>
pcl ip allocate --address 203.0.113.10 --network <network-id>

VM RAM is expressed in GB, matching the live PlusClouds resource model. Full provisioning requires both --image and --compute-pool; --draft-only is the explicit escape hatch when only a database record is intended. Numeric options are validated before credential or API work. VM --user-data must be UTF-8 text and is capped at 1 MiB. pcl vm create --wait emits one final result and polls by the returned VM id, so JSON/YAML output remains a single document. A timeout now includes perspective diagnostics; disk_count: 0 means the backend accepted the request but did not start disk provisioning. Do not replay the create automatically.

Output and global options

pcl --format json vm list
pcl --format yaml profile list
pcl --no-color vm list
pcl --quiet vm restart coolify
pcl --verbose vm list
pcl --api-base https://api.plusclouds.com vm list
pcl --timeout-ms 15000 vm list

Human-readable tables are the TTY default. JSON, YAML, and plain output are explicit machine modes. JSON list commands always emit arrays, including one-item lists. Diagnostics go to stderr. --quiet suppresses banners and human success noise, but never hides primary command data. When stdout is not a TTY, auto resolves to JSON for reads, mutations, status commands, and wait results. When the API returns more rows than requested by --per-page, PCL caps the page locally so --page and --per-page retain their CLI meaning.

Destructive commands prompt on a TTY and refuse noninteractive execution unless --yes (or the command's compatibility confirmation flag) is supplied.

pcl doctor always prints its report and returns exit code 1 when credentials are unavailable or the API check fails.

Storage/IP attach and detach actions resolve their UUID from the documented resource action catalog. Region reads use an undocumented compatibility route and require explicit --experimental opt-in. The documented storage-volume routes returned HTTP 404 in the latest authenticated read-only probe. PCL surfaces that failure and does not substitute VM disk-agent or storage-association routes.

SSH

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

Interactive SSH remains interactive. User precedence is --user, PCL_SSH_USER, VM metadata, then root; an explicit user@host overrides it. BatchMode=yes is used only for --cmd or --batch. Extra --ssh-arg values and host-key options are placed before the destination.

Environment

Variable	Effect
PCL_TOKEN	Highest-priority one-off token; bypasses profile storage.
PCL_TOKEN_PASSPHRASE	Passphrase for encrypted credential storage.
PCL_PROFILE	Active profile override.
PCL_FORMAT	auto, json, table, yaml, or plain.
PCL_API_BASE	API base override; HTTPS required except localhost development.
PCL_TIMEOUT_MS	Positive request timeout in milliseconds.
PCL_CONFIG_DIR	Config directory override.
NO_COLOR	Disables color when present.

Precedence for global settings is CLI option, environment variable, config value, then built-in default.

Verification

pnpm test
pnpm typecheck
pnpm lint
pnpm format:check
pnpm build

Authenticated smoke probes are opt-in. Mutating probes must use disposable resources and are not part of ordinary CI.

License

MIT