CLI overview

This page is a workflow-oriented map of the canasta command-line tool: which verbs cover which stages of operating a Canasta wiki, and how the CLI is invoked. It complements the per-command reference in the CLI: namespace (which is the canonical detail-level documentation, auto-generated from the CLI's own definitions).

What the CLI does

The Canasta CLI is the single tool you use to operate Canasta wikis throughout their lifecycle: provisioning the host, creating instances, managing wikis inside an instance, configuring extensions and skins, running maintenance, taking backups, and tearing down. It runs against either of the two supported orchestrators — Docker Compose for single-host deployments, Kubernetes for multi-host or HA setups — and the same verbs work on both.

For the orchestrator choice and where each is appropriate, see Help:Orchestrators. For the conceptual model of an "instance" and how multiple instances coexist on one host, see Help:General concepts.

Invocation

There are two equivalent ways to invoke the CLI. Both accept the same verbs and flags; the difference is what's on the host.

canasta-native — installs Ansible into a Python virtual environment on the host and runs playbooks directly. Faster startup, easier to read or customize the playbooks, and required for some commands (notably canasta install k8s-cp, which provisions software on the host).
canasta-docker — pulls a Canasta CLI Docker image and runs Ansible inside it. Only Docker is needed on the host. Convenient for ephemeral controllers; not suitable for installing host packages.

Both wrappers are installed via a single bootstrap (curl -fsSL https://get.canasta.wiki | bash for Docker mode; add -s -- --native for native). See Help:Installation for the install matrix and platform-specific prerequisites.

Targeting hosts

By default canasta manages instances on the local host (localhost). To manage instances on a remote host (typical for production: dedicated wiki host, controller on your laptop or a CI runner), pass --host <name>. Hosts can be SSH destinations or short names from a saved-host inventory. See Help:Multi-host management for the full targeting model.

The verbs by workflow stage

Lifecycle

The core verbs you'll use to operate any Canasta instance — create it, watch it, change state.

create — create a new instance from scratch (provisions storage, starts containers, runs MediaWiki's installer)
list — list all registered instances and their status
status — orchestrator-aware view of one instance's pods/containers, volumes, ingress, and TLS state
version — show the CLI version, the target Canasta image version, and per-instance image versions
start / stop / restart — change container state
scale — adjust replica counts (Kubernetes only)
delete — tear down an instance and remove it from the registry

Setup

install — install Docker, k3s control plane, k3s worker, or git-crypt on the target host (canasta-native only for some packages — see Help:Multi-node Kubernetes for the K8s topology rules)
uninstall — reverse the above on the target host
doctor — check that the target host has all the dependencies the CLI expects
host — manage the saved-host inventory (add, list, remove)

Wikis inside an instance

A Canasta instance can run a single wiki or many (a wiki farm). These verbs manage which wikis live inside.

add — add a new wiki to an existing instance
remove — remove a wiki from an instance (without tearing the instance down)
import — import a SQL dump into an existing wiki (e.g., migrating from another MediaWiki install)
export — export a wiki's database

For the conceptual model of wiki farms, including subdomain vs path-based routing, see Help:Wiki farms.

Configuration

config — read or modify per-instance environment values (get, set, unset, regenerate). Settings persist in the instance's .env file.

For configuration that lives in PHP settings rather than environment variables (LocalSettings.php-style), edit the per-wiki settings directory directly — see Help:General concepts.

Extensions and skins

extension — list / enable / disable bundled extensions
skin — list / enable / disable bundled skins

For installing additional extensions outside the bundled set, see Help:Extensions and skins.

Maintenance

maintenance — run MediaWiki maintenance scripts (maintenance/update.php and the standard catalog) without exec-ing into the container manually. Subverbs: exec, extension, script, update.

Backup and restore

backup — Restic-based backup operations: init, create, list, files, restore, diff, delete, check, unlock, purge, schedule (with set/list/remove).

For the conceptual model — what's captured, where it lands, RPO/RTO — see Help:Backup and restore and Help:Storage.

GitOps

gitops — manage instance configuration in a git repository for version-controlled, multi-environment workflows. Subverbs: init, join, add, rm, push, pull, sync, status, diff, fix-submodules.

For the source/sink role model and shared/per-host variable rules, see Help:GitOps.

Kubernetes-specific

storage — manage shared StorageClasses on the cluster (list, setup nfs, setup efs). See Help:Storage.
argocd — interact with the bundled Argo CD controller (password, apps, ui) when the cluster's API isn't reachable from the controller.

Sitemaps

sitemap — generate or remove a wiki's sitemap.xml (generate, remove).

Upgrades

upgrade — pull the latest playbooks (or CLI Docker image), then upgrade all registered instances. See Help:Upgrading for the upgrade flow.

Development mode

devmode — toggle a development-friendly state (enable, disable) that mounts the MediaWiki source tree from the instance directory for live editing. See Help:Development mode.

Where to find per-command details

Every verb above links to its CLI: page, which is the canonical reference for that command — synopsis, parameters with types and defaults, examples, exit codes, and orchestrator-specific behavior. Those pages are auto-generated from the CLI's command definitions and stay in lockstep with the shipped tool, so they're the source of truth for "what does this flag actually do" questions.

This Help: page is the conceptual map; CLI: pages are the API reference. The two together cover every operation Canasta supports.