Quantum CLI

quantum-cli is a command-line client for Planetary Quantum’s Docker hosting platform.
Documentation is available at https://docs.planetary-quantum.com/.

Latest Release: 2.8.13

Use the table to find the release for your system:

• Alternative: download all versions
• Verification: all checksums (sha512)

Or use our Docker image at:

• r.planetary-quantum.com/quantum-public/cli:2.8.13
• quay.io/pngmbh/quantum-cli:2.8.13 (mirror)

Use a specific tag:

docker run -it --rm \
    r.planetary-quantum.com/quantum-public/cli:2.8.13 \
    quantum-cli --help

Or, a fluent tag, such as:

docker run -it --rm \
    r.planetary-quantum.com/quantum-public/cli:2 \
    quantum-cli --help

Updates

We recommend to always use the latest quantum-cli version. We strive to keep it backwards-compatible within major versions for the setup on your side (env vars, .quantum files, etc).

• quantum-cli selfupdate
• keep your docker image references pointing to :2

Changelog

Patch level updates are not always mentioned here, neither are updates to this page or related documentation updates that don’t have code changes in quantum-cli.

2.8.0

• updates:
  • Windows cli for arm64
  • Docker image for arm64 (--platform=linux/arm64/v8)
• internal updates:
  • updated base Docker images
  • dependency updates
  • go 1.19
  • workflow updates

2.7.0

• feature: quantum-cli exec - get a shell or run commands on a container
  • use quantum-cli exec --endpoint myendpoint --stack mystack --service foo to get a shell (if the container has one installed)
  • run other commands with quantum-cli exec ... --command "echo hello"
  • for details, see quantum-cli exec --help
• feature: quantum-cli ps - list running tasks
  • quantum-cli ps --endpoint myendpoint with an optional --stack filter
  • use quantum-cli ps ... --all to also see failed and shutdown tasks (with error messages, if any)
  • for details, see quantum-cli ps --help

2.6.0

• enhancement: quantum-cli now detects if an image is declared with an environment variable (something like image: alpine:${ALPINE_VERSION} and the env variable is empty or not set. Docker itself has always rejected that (the resulting image would be alpine:, which is invalid because of the : at the end), but quantum-cli has a friendlier error message.

2.5.3

• enhancement: with this, and the latest update to the Quantum platform, quantum-cli migration can now migrate volumes of practically unlimited size (multiple GBs)

2.5.2

• bugfix: lowest-level help output (e.g. quantum-cli stack update --help) does not check login credentials anymore

2.5.1

• bugfix: quantum-cli migration now also copies volumes mounted under multi-level paths

2.5.0

• feature: new experimental quantum-cli migration subcommand, to migrate stacks including volumes and their contents and including docker config objects from one Quantum cluster to another.

  quantum-cli migration automatically reads the volumes and configs to migrate from the stack configuration. After copying everything over, it can optionally start the new stack on the target cluster, or leave that to you.

  Note that while quantum-cli migration tries to be reasonably clever, it might not be enough for a fully automated migration from cluster to cluster in some cases, as other deployment options like node-pinnings or hostnames might need adjusting.

  Volume contents are temporarily downloaded to your local machine, so enough free HDD space and a good internet connection is advisable.

  For details, see quantum-cli migration --help.

2.4.1

• feature: new environment variable QUANTUM_STACK
• feature: new alias self-update for quantum-cli selfupdate
• (a previous changelog erroneously listed this as 2.5.0 - 2.4.1 is the correct release)

2.4.0

• feature: quantum-cli stack rm, deletes a stack

2.3.2

• bugfix: image pre-pull failures did not stop deployments

2.3.0

Welcome to the year 2021 where the pandemic is still ongoing, but we’re alive and still kicking!

We relaunched our websites:

• www.planetary-quantum.com (only in German for now)
• docs.planetary-quantum.com (only in English ;), a new and improved documentation website)

The 2.3.0 release of the CLI includes the following updates:

• update: improvements to the CLI documentation (also available via --help) to streamline the user experience
• update: the handling and use of environment variables was improved - this feature cuts down on code required on your end to implement CI and CD workflows
• update: support for ARM
  • darwin
  • linux
  • windows
• update: image pre-pull on deployments now happens in parallel
• update: progress bars for image pre-pull and service updates
• drop: support for darwin/386 (32bit builds on OSX)

2.2.4

• update: --help now also lists all subcommands, and all the possible config files
• update: validate --help now also explains the .quantum file syntax

2.2.3

• bugfix: allow docker-compose version 2.0 in “stacks” on non-Swarm/Docker standalone
• update: display a warning when an environment is used during create/update which does not exist in .quantum

2.2.2

• bugfix for the image pre-pull (used to fail for certain combinations of images from multiple registries with authentication enabled)

2.2.1

• bugfix for the image pre-pull (used to fail for non-namespaced images with numeric versions, e.g. foo:1.2.3)

2.2.0

• stack create/stack update will now try to pull the images from your compose/stack file onto the specified Quantum endpoint before starting the deployment. In case of problems with the images, this will show a nicer error message than Docker’s generic “replication failed”.
  • related: new --no-pre-pull flag for stack create/stack update to switch that off
• quantum-cli validate now also checks if all the configured docker-compose/stack files are there, and at least at version 3.0
  • related: new --no-validate flag for stack create/stack update to switch that off (validate always runs before deployments)

2.1.6

• more helpful error messages on stack creation, when the stack name is already taken

2.1.5

• regression fix: when creating new stacks, they were previously set to private, i.e. only visible to the user that created them. They are now always public by default again (visible to all users with access to the Quantum endpoint).

2.1.4

• when using the --wait flag with stack update or stack create, the output now includes the service name, instead of the service ID.

2.1.3

• bugfix: nicer error reporting when endpoint or stack name are missing, for commands that require them
• docker images now mirrored at quay.io/pngmbh/quantum-cli
• docker images now have a :latest version that always points to the latest release

2.1.2

• bugfix: all three equivalent ways to specify the endpoint are working again:

  quantum-cli stack ls --endpoint foo
  QUANTUM_ENDPOINT=foo quantum-cli stack ls
  PORTAINER_ENDPOINT=foo quantum-cli stack ls # was broken since 2.0.0
  

2.1.1

• stack creation is now compatible with Portainer version >= 1.23.0 (older Portainer versions are also still supported). Planetary Quantum will update to Portainer 1.23.0 in the weeks after this release.

2.1.0

• login tokens are now cached (in ~/.cache/quantum), speeding up normal usage

2.0.3

• bugfix: better error handling/reporting during login phase

2.0.2

• bugfix: http user agent during login phase now set to quantum-cli
• enhancement: http user agent now includes version number

2.0.1

• bugfix: selfupdate on MacOS Catalina now reports the new version number

2.0.0

• URL changes:
  • Planetary Quantum now lives at console.planetary-quantum.com
  • selfupdate download URL switched to cli.planetary-quantum.com
• login method change: logins via id.planetary-quantum.com are now supported
• related: the environment variables to control the host and login are now called QUANTUM_(USER|PASSWORD|HOST) instead of PORTAINER_(USER|PASSWORD|HOST). The old variable names will also keep working though.

1.6.0

• new option for stack update and stack create: --wait
  This will make quantum-cli wait until the deployment is completely done:
  • all services are updated
  • the desired number of replications are running

  It will exit non-successfully in case of update failures or rollbacks (if the given service has a rollback_config).

1.5.0

• new option for stack update: --create
  This will create the stack if it doesn’t exist, and update it otherwise.
• the .quantum file is now optional
• bugfix: newly-created stacks are now accessible to non-admins

1.4.7

• bugfix for docker image: using the correct libc now

1.4.0

• new command: quantum-cli selfupdate

1.3.5

• bugfix: also print stderr of commands run via .quantum files

1.3.4

• bugfix: check exit codes of build/publish commands from the .quantum file