| name | quantum-cli |
| description | Work with Planetary Quantum stacks and endpoints via `quantum-cli`. Use this skill when inspecting endpoints, listing stacks or tasks, validating `.quantum` configuration, deploying or removing stacks, opening remote shells with `exec`, or migrating stacks between endpoints. |
Quantum CLI
When to Use
Use this skill for Planetary Quantum operational work, especially when the task involves:
- checking authentication, console connectivity, or endpoint availability
- listing endpoints, stacks, services, or tasks
- validating
.quantum configuration before deployment
- creating, updating, or removing stacks
- opening a remote shell or running one-off commands with
exec
- migrating a stack including volumes and configs between endpoints
- checking environment-variable based deploy setup in CI or local shells
If MCP tools for Quantum are available in the session, prefer them for read-only inventory work. Use quantum-cli when you need CLI-native flows such as deploys, validation, migrations, auth checks, or remote command execution.
Guardrails
- Start with read-only inspection before any mutating command.
- Never guess flags. Run
quantum-cli help or quantum-cli <subcommand> --help if a command shape is uncertain.
- Use shell-safe placeholders like
"$QUANTUM_ENDPOINT" and "$QUANTUM_STACK" in examples. Avoid angle-bracket placeholders in shell snippets.
- Do not expose API keys, passwords, tokens, or full environment dumps in the response.
- Treat
--no-validate and --no-pre-pull as exceptions. The docs explicitly say they are not recommended.
- For deploys, prefer
--wait so completion state is observable.
- For stack deletion or migration, verify the source and target identifiers explicitly before running the command.
- For migrations involving databases, assume the data can be corrupted if the database is still writing. Prefer application/database replication or stop writes first.
- The CLI still accepts
PORTAINER_* environment variables, but QUANTUM_* names are the current interface and should be preferred.
Default Workflow
1. Confirm CLI and target
Start by checking CLI availability, effective auth inputs, and available targets:
command -v quantum-cli
test -n "$QUANTUM_API_KEY" || { test -n "$QUANTUM_USER" && test -n "$QUANTUM_PASSWORD"; }
quantum-cli endpoints ls
quantum-cli stacks ls --endpoint "$QUANTUM_ENDPOINT"
If the task depends on environment-driven configuration, check the effective variable source before mutating anything.
2. Inspect runtime state
Before changing anything, inspect current tasks:
quantum-cli ps --endpoint "$QUANTUM_ENDPOINT" --stack "$QUANTUM_STACK"
quantum-cli ps --endpoint "$QUANTUM_ENDPOINT" --stack "$QUANTUM_STACK" --service "$QUANTUM_SERVICE" --all
Use --all when diagnosing restarts, failed rollouts, or non-running tasks.
3. Validate config before deploy
If the task touches a deployable project with a .quantum file, validate first:
quantum-cli validate --help
quantum-cli validate --project "$PROJECT_DIR"
quantum-cli stacks update --help
The docs also support environment-variable driven deployments. quantum-cli injects environment variables during deployment without modifying the stack file in-place.
4. Deploy safely
Preferred deploy pattern:
quantum-cli stacks update \
--endpoint "$QUANTUM_ENDPOINT" \
--stack "$QUANTUM_STACK" \
--project "$PROJECT_DIR" \
--environment "$QUANTUM_ENVIRONMENT" \
--wait
Use --create only when the intent is to create the stack if missing. Use stacks create when the operation should be explicitly create-only.
5. Verify after deploy
After deployment, re-check tasks:
quantum-cli ps --endpoint "$QUANTUM_ENDPOINT" --stack "$QUANTUM_STACK" --all
If needed, inspect a specific workload with exec.
Remote Debugging with exec
Use exec only after identifying the correct target container via ps.
Interactive shell:
quantum-cli exec --endpoint "$QUANTUM_ENDPOINT" --stack "$QUANTUM_STACK" --service "$QUANTUM_SERVICE"
One-off command:
quantum-cli exec \
--endpoint "$QUANTUM_ENDPOINT" \
--stack "$QUANTUM_STACK" \
--service "$QUANTUM_SERVICE" \
--command "sh -lc 'pwd && ls -la'"
Useful options:
--slot <n> to target a specific replica--container <id> when a direct container selection is safer than service selection--command-user <user> when command context matters
shell and ssh are documented aliases for exec.
Stack Lifecycle Coverage
According to the current Quantum CLI reference, the tool covers at least these operational areas:
endpoints ls for endpoint inventorystacks create, stacks ls, stacks update, and stacks rmvalidate for .quantum projectsps for task inspectionexec, shell, and ssh for remote shell and command executionmigration / migrate for stack duplication across endpointsselfupdate / self-update for updating the CLI itself
This capability list is taken from the official CLI reference, not inferred from repo usage.
Environment Variables
The docs describe two environment-variable layers:
- global auth and host config such as
QUANTUM_HOST; the currently documented standard path is QUANTUM_USER plus QUANTUM_PASSWORD, while this repo is in the process of moving toward QUANTUM_API_KEY
- command-scoped selectors such as
QUANTUM_ENDPOINT, QUANTUM_STACK, QUANTUM_SERVICE, and migration-specific variables
The docs also note compatibility aliases such as PORTAINER_HOST, PORTAINER_USER, PORTAINER_PASSWORD, and PORTAINER_ENDPOINT. Treat those as compatibility inputs, not the preferred naming scheme.
When the task involves CI or a scripted deploy, prefer explicit environment variables over interactive flags and avoid echoing them back to the user. For generic Quantum CLI usage, assume QUANTUM_USER plus QUANTUM_PASSWORD unless the repo or environment already documents QUANTUM_API_KEY for that deployment path.
Migration Notes
quantum-cli migration can copy a whole stack including volumes and configs from one endpoint to another.
Use it carefully:
- verify source endpoint, target endpoint, source stack, and target stack names explicitly
- prefer a maintenance window or at least stop traffic first
- treat running databases as unsafe to copy at the volume level unless you know the storage is quiesced
- use database-native replication instead of raw volume copying when the task is a database migration
Common Patterns
See common-patterns.md for compact examples covering endpoint discovery, stack inspection, validated deploys, removals, exec, migrations, and CI-style environment-variable usage.
Response Expectations
When reporting results back to the user:
- name the endpoint, stack, and service you inspected or changed
- state whether the action was read-only or mutating
- summarize the relevant task, deployment, or migration state
- call out any assumptions, especially environment selection and target stack names
- if a deploy or migration was not executed, say whether validation, auth, target discovery, or safety concerns were the blocker
