CLI reference

The weikio CLI is one program file for Linux and Windows. Every command is a call to the hub’s HTTP API, so the CLI can do everything the platform does. Developers use it to publish and deploy integrations, operators use it to run the installation and pipelines use it to apply what is in Git. Install the CLI gives the install command for each system, and weikio --help lists the commands of this reference on your own machine.

These pages describe the weikio CLI of 2026.2.1. weikio version prints the release of your CLI and of the hub it connects to.

Command groups#

The operations that run on a hub server without the API, such as init, backup and restore, belong to the backend image and are on the weikio-backend page.

How commands are written#

Commands that read or delete something put the verb first, as in weikio get integrations, weikio describe deployment finance/erp-invoice-export and weikio delete apikey <key-id>. Commands that create or change something put the kind first, as in weikio project create, weikio env set and weikio member add. weikio create <kind> works as well for every kind that weikio <kind> create creates, for anyone used to kubectl.

An integration, API or other record of a project is written <project>/<name>, such as finance/erp-invoice-export, or as the name alone when the project comes from somewhere else. The CLI takes the project from the first of these it finds:

1. metadata.project in the document
2. --project
3. the nearest project.yaml in a parent folder, for the commands that read files
4. the current context

When none of them gives a project, the command stops with exit code 2, and when a document and --project disagree, the command refuses instead of choosing one.

Names use lower-case letters, digits and hyphens. Variables and secrets are the exception, because they follow Camel’s property names: letters of either case, digits, ., _ and -. Every record also has an ID that never changes, and weikio rename <kind> <name> <new-name> changes a record’s name while it keeps its ID, its history and everything stored for it.

Contexts and defaults#

A command reads its server, key, project and environment from flags first, then from the environment variables WEIKIO_SERVER, WEIKIO_API_KEY, WEIKIO_PROJECT, WEIKIO_ENV and WEIKIO_CONTEXT, and last from the current context. Login and contexts describes contexts.

A production environment is protected. A command that changes something in it needs the environment from --env, from metadata.environment in the document or from WEIKIO_ENV, and never takes it from the context alone. Without one of them, the command stops with exit code 2 and prints the same command with --env added.

Flags every command accepts#

Every command that changes something also accepts --reason "<text>", which is stored with the audit record of the change. A pipeline sets WEIKIO_REASON once, for example to the commit’s subject line. apply, run and version create also record where the change came from, and in GitHub Actions, GitLab CI and Azure Pipelines the CLI fills that in from the pipeline’s own variables.

A command that deletes something, changes a production environment or restarts a deployment in production asks for confirmation first. apply asks only for --prune, and variable set and secret set ask only when --restart reaches a deployment in production. -y answers yes, and without a terminal to ask on the command refuses with exit code 2 and prints the command with -y added.

Output#

A list prints a table with upper-case headers and a dash for an empty cell, and a single record prints one Label: and value to a line. Under -o json and -o yaml standard output has only the records, as the API returns them, so a script can read them. Every command that changes something starts with a Target: line that says which server, project and environment it writes to and where each value came from:

Target: https://hub.example, project finance (from finance/project.yaml), environment production (--env)

A write prints one line for each thing it changed, such as integration finance/hello created (version 0.1.0, built in 4.0 s). An error is one error: line with the reason, followed by the command that fixes it, so you can copy the next step from the terminal.

Every time the CLI prints is in UTC and says so, such as 2026-10-16 08:21 UTC, and an age is written as 4 min ago. Sizes use binary units, such as 512 MiB and 1.5 GiB. A length of time is written with units and without spaces, such as 500ms, 30s, 1h30m or 7d, and a --since counts back from now.

weikio export is the command whose output applies again unchanged with weikio apply. The JSON of the other commands is the API’s own records.

Roles in this reference#

Each command says who can run it. A grant gives a person or a key one role in one project, for some or all environments and optionally for named integrations and APIs only, and a role is a set of verbs:

The seeded roles are viewer (read), editor (read, author, operate and reveal), deployer (the editor’s verbs with deploy and entity-store-policy) and admin (every verb). A platform administrator is a user or key with the platform administrator flag, which every command about the installation itself needs: projects, environments, roles, agents, users, providers and settings.

Exit codes#

Scripts and pipelines can branch on the exit code:

weikio diff has its own codes, so a pipeline can tell the cases apart: 0 when nothing would change, 2 when something would and 7 when something would be refused. A nightly weikio diff -f ./finance --env production with exit code 2 means someone changed production by hand since the last apply.

See also#

• Install the CLI
• Keep integrations in Git
• HTTP API
• Document kinds