CLI reference
Weik.io 2026.2Look up the commands of the weikio CLI by group, in the order of weikio --help, and the rules every command follows.
On this page
Each command of the weikio CLI calls the HTTP API of your Weik.io installation, whether you run the CLI in a terminal or in a pipeline that applies what is in Git. The CLI is a single program file for Linux and Windows, and Install the CLI gives the install command for each system.
These pages describe the weikio CLI of 2026.2.2 and list its commands by group, in the same order as weikio --help. weikio version prints the release of your CLI and of the installation it connects to.
Command groups#
Commands that run on a hub server without the API, such as backup and restore, are part of the backend image. The weikio-backend page describes them.
How commands are written#
Commands that read or delete something put the verb first, as in weikio get integrations and weikio delete apikey <key-id>. Commands that create or change something put the kind first, as in weikio project create and weikio env set. If you’re used to kubectl, you can also write weikio create <kind> for every kind that weikio <kind> create creates.
You refer to a record of a project, such as an integration or an API, as <project>/<name>, for example finance/erp-invoice-export. When the project comes from somewhere else, the name alone is enough. The CLI gets the project from the first of these it finds:
metadata.projectin the document--projectWEIKIO_PROJECT- The nearest
project.yamlin a parent folder, for the commands that read files - The current context
When none of them gives a project, the command stops with exit code 2. When a document and --project disagree, the command refuses instead of choosing one.
Names use these characters:
- Lower-case letters
- Digits
- Hyphens
The names of variables and secrets follow Camel’s property names instead, which also allow upper-case letters and the characters . and _.
Every record also has an ID that never changes. weikio rename <kind> <name> <new-name> changes only a record’s name, and the record keeps its ID and everything stored for it, such as its history.
Contexts and defaults#
A command gets the installation’s address, the key, the project and the environment from the first of these that sets them:
- The command’s flags
- The environment variables
WEIKIO_SERVER,WEIKIO_API_KEY,WEIKIO_PROJECT,WEIKIO_ENVandWEIKIO_CONTEXT - The current context
Login and contexts describes contexts.
A production environment is protected. A command that changes something in it never gets the environment from the context alone, and needs it from one of these:
--envmetadata.environmentin the documentWEIKIO_ENV
Without one of them, the command stops with exit code 2 and prints the same command with --env added.
Flags every command accepts#
| Flag | What it does |
|---|---|
-- |
Uses this context instead of the current one. |
-- |
Uses this address instead of the context’s. |
-- |
Works in this project. |
--env, -- |
Works in this environment. |
-o, -- |
Sets the output format to table, json or yaml. The default is table. |
-- |
Prints a table without its header row. |
-q |
Prints only the names, one to a line. |
-- |
Prints without colour. |
-h, --help |
Shows the command’s help. |
Every command that changes something also accepts --reason "<text>", and Weik.io stores the text with the audit record of the change. A pipeline can set WEIKIO_REASON once, for example to the commit’s subject line.
These commands also record where the change came from:
applyrunversion create
In GitHub Actions, GitLab CI and Azure Pipelines, the CLI fills that in from the pipeline’s variables.
A command asks for confirmation first when it does one of these:
- Deletes something
- Changes a production environment
- Restarts a deployment in production
apply asks only about --prune. variable set and secret set ask only when --restart reaches a deployment in production.
-y answers yes. Without a terminal to ask on, the command refuses with exit code 2 and prints the command with -y added.
Output#
A list prints as a table with upper-case headers and a dash in each empty cell. A single record prints one Label: and its value to a line.
When a table has no rows, standard output stays empty, without even the header row. The CLI says on standard error that nothing was found, such as No problems found., or No problems match the filters. when you gave filters.
With -o json or -o yaml, standard output has only the records as the API returns them, for a script to read.
Every command that changes something first prints a Target: line. The line says which installation, project and environment the command 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.
The CLI uses these forms for times and sizes:
| Value | How it’s written |
|---|---|
| A time the CLI prints | In UTC, which the time says, such as 2026- |
| An age | Such as 4m ago |
| A size | In binary units, such as 512 MiB and 1.5 GiB |
| A length of time you give a flag | With units and without spaces, such as 500ms, 30s, 1h30m or 7d |
A --since value counts back from now.
weikio export is the one command whose output you can give to weikio apply unchanged. The JSON of the other commands is the API’s records.
Roles in this reference#
Each command on these pages says who can run it. A grant gives a person or a key one role in one project, for some or all environments, and can be limited to named integrations and APIs. What a grant allows depends on which of these verbs its role has:
| Verb | What it allows |
|---|---|
read |
Reading the project’s records, logs, metrics and traces |
author |
Writing integrations, APIs, kamelets and variables |
operate |
Setting secrets, starting, stopping and invoking deployments, and resending events |
reveal |
Showing a secret’s value, where the environment allows it |
deploy |
Deploying, promoting and rolling back into an environment |
entity- |
Creating and changing entity types |
members |
Adding and removing the project’s members |
Weik.io has these roles from the start:
| Role | Verbs |
|---|---|
viewer |
read |
editor |
read, author, operate and reveal |
deployer |
The editor’s verbs, with deploy and entity- |
admin |
Every verb |
A platform administrator is a user or key with the platform administrator flag. Every command that manages one of these needs the flag:
- Projects
- Environments
- Roles
- Agents
- Users
- Identity providers
- Settings
Exit codes#
Scripts and pipelines can branch on the exit code:
| Code | Meaning |
|---|---|
| 0 | The command succeeded, including a write that changed nothing. |
| 1 | Weik.io refused the change for a product reason, such as a version that already exists or a secret with no value. The message ends with the command that fixes it. |
| 2 | A usage error, such as an unknown flag, a missing --env for a production environment, a project that can’t be resolved or a name that breaks the naming rule. |
| 3 | The key is missing, expired, revoked or not allowed to do this. |
| 4 | The record wasn’t found. |
| 5 | The record changed since it was read, and the command shows the current one. |
| 6 | Weik.io couldn’t be reached or wasn’t ready, and nothing was written. |
| 7 | weikio apply wrote part of the set and refused the rest, or weikio diff found a document it would refuse. |
| 8 | A document or folder isn’t valid. |
| 130 | Interrupted with Ctrl+C. weikio run and weikio logs -f stop following and the integration keeps running. |
When a delete asks you to type the record’s name and you type another, the command deletes nothing and exits with 2.
weikio diff has codes of its own, so a pipeline can tell these cases apart:
| Code | Meaning |
|---|---|
| 0 | Nothing would change. |
| 2 | Something would change. |
| 7 | Something would be refused. |
When a nightly weikio diff -f ./finance --env production exits with 2, someone changed production by hand since the last apply.