v3 Migration #

This document highlights the changes and additions in version 3 of the quantum-cli tool.

New Features #

API Key Authentication #

v3 only supports API key authentication.

Acquire an API key:

1. Login: https://console.planetary-quantum.com
2. Go to your profile: https://console.planetary-quantum.com/#!/account
3. Create an API key

API keys are valid for up to one year. Administrators receive monthly reporting of API keys in use and their expiration.

New commands available with quantum-cli auth:

NAME:
   quantum-cli auth - Authentication management

USAGE:
   quantum-cli auth [command [command options]]

COMMANDS:
   status    Show authentication status
   keys, ls  List API keys from the server
   rotate    Rotate API key (replace cached key with new one)
   logout    Clear cached credentials

OPTIONS:
   --help, -h  show help

Deployments #

The quantum-cli stack deploy command now reads the following files by default:

• compose.[yaml,yml]
• docker-compose.[yaml,yml]
• stack.[yaml,yml]

In addition, you can use any YAML file with --file (-f):

quantum-cli stack deploy --file my-stack.yaml

JSON #

All list commands now support JSON output:

quantum-cli stack ls -o json
quantum-cli endpoint ls -o json
quantum-cli ps -o json
quantum-cli auth keys ls -o json

MCP #

quantum-cli mcp serve starts an MCP server that you can use with your favorite agent.

For example:

claude mcp add --scope user \
  quantum-cli -- quantum-cli mcp serve

codex mcp add --scope user \
  quantum-cli -- quantum-cli mcp serve

Or add the following JSON:

{
  "mcpServers": {
    "quantum-cli": {
      "command": "quantum-cli",
      "args": ["mcp", "serve"]
    }
  }
}

The MCP is read-only by default but offers additional tools as well. Please see the MCP AI section for more details.

Changes #

ps command #

The ps command now has a show alias:

quantum-cli show

Caching #

v2 introduced performance improvements through caching. This cache lives in ~/.cache/quantum.

If you use quantum-cli via Docker, we recommend mounting the folder. Note the updated path:

docker run -it --rm \
-   -v $HOME/.cache/quantum:/root/.cache/quantum:rw \
+   -v $HOME/.cache/quantum:/home/quantum/.cache/quantum:rw \
    r.planetary-quantum.com/quantum-public/cli:3 \
    --help

Docker/OCI Image #

Changes to the quantum-cli OCI image.

Security #

To support runtimes such as Podman or Kubernetes, the Docker image now runs rootless.

Invocation [BREAKING] #

We’ve updated the ENTRYPOINT:

docker run -it --rm \
    -v $HOME/.cache/quantum:/home/quantum/.cache/quantum:rw \
-   r.planetary-quantum.com/quantum-public/cli:2 \
+   r.planetary-quantum.com/quantum-public/cli:3 \
-   quantum-cli --help
+   --help

GitHub Action [BREAKING] #

Our GitHub Action is updated to support API key authentication:

-  - uses: hostwithquantum/setup-quantum-cli@v1
+  - uses: hostwithquantum/setup-quantum-cli@v2
    with:
-     username: ${{ secrets.QUANTUM_USERNAME }}
-     password: ${{ secrets.QUANTUM_PASSWORD }}
+     api-key: ${{ secrets.QUANTUM_API_KEY }}
  - run: quantum-cli auth status

Improved logging #

quantum-cli now supports configurable log formats and output destinations:

quantum-cli --log-format=json    # default: text
quantum-cli --log-output=stderr  # default: stdout
quantum-cli --log-output=off     # disable logging

These options can also be set via environment variables. See quantum-cli -h for details.

Log messages have also been cleaned up for consistency.

Removed #

stack create and stack update #

aliases #

Going forward the create and update have been unified into a single top-level deploy command. In addition, the flags for --create and --wait have been removed. The feature itself does not change, but you need to use quantum-cli stack deploy exclusively.

Examples:

- quantum-cli stack create --update --wait
+ quantum-cli stack deploy

- quantum-cli stack update --create --wait
+ quantum-cli stack deploy

options #

The --environment (-e) and --project options were used by the .quantum configuration file and have been removed.

Replace environment with the --file (-f) option:

quantum-cli stack deploy -f my-stack.yaml

validate command #

The validate command and the --project option were used for the .quantum configuration file and has been removed. Use standard tooling such as docker compose config --dry-run to validate your compose files.

User & password based authentication #

User and password authentication was removed and replaced by API key authentication:

• quantum-cli --username (-u): removed
• QUANTUM_USER, PORTAINER_USER (environment variables): removed
• quantum-cli --password (-p): removed
• QUANTUM_PASSWORD, PORTAINER_PASSWORD (environment variables): removed

.quantum file #

The .quantum file supported in quantum-cli stack create (and update) has been removed. To use a custom stack configuration file, use --file (-f) going forward.