Integrations, versions and the developer loop

An integration is a folder of Apache Camel files written as you would write them for Camel JBang: routes in YAML, XML or Java, kamelets, application.properties, jars and any other file a route uses. weikio apply publishes the folder as a new version, weikio deploy runs a version in an environment and weikio run does both and then follows the logs.

A published version never changes. Without a version: line in integration.yaml, the first version is 0.1.0 and each apply with changed files publishes the next patch version. With a version: line, --bump raises it and rewrites the file. The CLI uploads only the files the hub doesn’t have yet and resumes an interrupted upload.

Commands on this page#

The flags every command accepts, such as --env, --project, -o and --context, are on the CLI reference page and are left out of the tables below.

weikio init#

Scaffold an integration directory or a generated document. --kind writes one of the generated kinds instead of a Camel folder: a file transfer (mft), a schedule, an event source, channel or subscription, change tracking or an API. Names use lower-case letters, digits and hyphens.

weikio init <name> [--kind integration|mft|schedule|event-source|event-channel|event-subscription|change-tracking|api] [--camel-version V] [--no-manifest] [--project P]

Who can run it: nothing on the server, because the command runs on your machine.

API: GET /api/v1/camel-lines.

$ weikio init HelloWorld

error: 'HelloWorld' isn't a valid name. A name can use only lower-case letters, digits and hyphens, such as 'hello-world'.

$ weikio init hello

Created hello/
  hello.camel.yaml        timer -> log, runs every 5 s
  application.properties  message=hello from weikio
  integration.yaml        name hello, other fields as commented examples

Next, to run it in project sandbox and environment devtest:
  weikio run ./hello

weikio validate#

Run the checks an apply runs, without sending anything. It runs offline, so a pipeline can fail early without a key. It checks each document against its kind’s schema and the naming rules, and with a context it also checks what only the server knows. Camel’s own check of a route’s steps runs when apply builds the version.

weikio validate -f <path>...

Who can run it: nothing for the offline checks, and an API key for the checks against the hub.

API: GET /api/v1/schemas, GET /api/v1/camel-lines, GET /api/v1/projects/{project}/kamelets.

weikio apply#

Publish documents and integration directories. apply publishes: integration folders become versions and every other document is created or updated. A deployment runs a new version only when it follows latest or when a deployment document of the set sets that version. Each document gets one row, created, updated, unchanged, deleted or refused, and a set with refused rows exits 7, or 1 when every row is refused. --prune <name> deletes what earlier applies of the same paths under that name created and the files no longer contain, which is how a deleted file removes a record in GitOps.

weikio apply -f <path>... [--project P] [--env E] [--bump patch|minor|major] [--version X] [--prune <name>] [--dry-run] [-y]

Who can run it: the grant each document needs: author for the project’s documents, deploy for a deployment and operate for a secret.

API: POST /api/v1/projects/{project}/integrations/{name}/source/missing, PUT /api/v1/projects/{project}/integrations/{name}/source?dryRun=&version=, PUT /api/v1/configuration?environment=&dryRun=&builds=, POST /api/v1/configuration/prune?environment=&dryRun=.

$ weikio apply -f ./finance/erp-invoice-export

Target: https://hub.example, project finance (from finance/project.yaml), environment devtest (context)
integration finance/erp-invoice-export refused: Version '1.0.0' is already published.
    Set another with --version <version>, or bump it with --bump patch.

$ weikio apply -f ./finance/erp-invoice-export --bump minor

Target: https://hub.example, project finance (from finance/project.yaml), environment devtest (context)
Uploading 2/9 files, building...
integration finance/erp-invoice-export updated (version 1.1.0, built in 17.3 s)
integration.yaml updated to 1.1.0

Nothing new is running yet. To run it:
  weikio deploy -f ./finance/erp-invoice-export --env devtest

weikio diff#

Show what an apply would do. Exits 2 when anything would change and 7 when anything would be refused. diff runs the same checks as apply on the server and prints what would change, field by field for small documents. It exits 0 when nothing would change, 2 when something would and 7 when a document would be refused, so a nightly pipeline that runs it against production finds changes made by hand.

weikio diff -f <path>... [--project P] [--env E] [--prune <name>]

Who can run it: a grant on the project whose role has author.

API: PUT /api/v1/configuration?dryRun=true&builds=, GET /api/v1/configuration/export?project=&environment=, PUT /api/v1/projects/{project}/integrations/{name}/source?dryRun=true&version=, POST /api/v1/configuration/prune?environment=&dryRun=true.

weikio run#

Publish a directory, deploy it and follow its logs. run is the development shortcut: it applies the folder, deploys every integration it published as latest to the environment and follows their logs. Ctrl-C stops following and the integration keeps running. When the folder declares a version and its files changed, run bumps the patch version for you.

weikio run <dir> [--env E] [--project P] [--bump ...] [--no-logs]

Who can run it: a grant on the project with author, and deploy and read in the environment.

API: PATCH /api/v1/environments/{environment}/projects/{project}/deployments/{name}, GET /api/v1/projects/{project}/integrations/{name}/status, GET /api/v1/logs/tail.

$ weikio run ./hello

Target: https://hub.example, project sandbox (context), environment devtest (context)
integration sandbox/hello created (version 0.1.0, built in 16.2 s)
deployment devtest/sandbox/hello created (follows latest)
Following the log lines of sandbox/hello. Ctrl-C stops following, and the integration keeps running.
09:14:07.113 UTC INFO  hello  agent-fi-01  Exchange[ExchangePattern: InOnly, BodyType: String, Body: hello from weikio]
09:14:12.114 UTC INFO  hello  agent-fi-01  Exchange[ExchangePattern: InOnly, BodyType: String, Body: hello from weikio]
^C

$ weikio run ./hello                  # after editing the route

Target: https://hub.example, project sandbox (context), environment devtest (context)
integration sandbox/hello updated (version 0.1.1, built in 15.9 s)
deployment devtest/sandbox/hello updated (follows latest)

weikio dev run#

Run a directory here against an environment’s resolved configuration. The route runs on your machine with Camel JBang (camel run). The CLI hands it the environment’s resolved configuration, so {{erp-url}} resolves as it does on the platform. Secrets stay out of the run unless you add --with-secrets, which needs reveal in the environment.

weikio dev run <dir> [--env E] [--project P] [--reload] [--with-secrets]

Who can run it: a grant with read in the environment, and reveal with --with-secrets.

API: GET /api/v1/camel-lines, GET /api/v1/environments/{environment}/projects/{project}/deployments/{name}/configuration?name=..., GET /api/v1/projects/{project}/kamelets/_local, GET /api/v1/camel-lines/{line}/cluster-jar, GET /api/v1/environments/{environment}/projects/{project}/secrets/{name}/reveal, GET /api/v1/projects/{project}/secrets/{name}/reveal, GET /api/v1/environments/{environment}/projects/{project}/integrations/{i}/secrets/{name}/reveal, GET /api/v1/projects/{project}/integrations/{i}/secrets/{name}/reveal.

weikio get integrations#

List the integrations of a project.

weikio get integrations [--project P] [--kind K] [-l k=v]

Who can run it: a grant on the project whose role has read.

API: GET /api/v1/projects/{project}/integrations?type=.

weikio describe integration#

Read one integration with its versions and deployments.

weikio describe integration <p>/<n> [--readme | --source-file <path> [--version X]]

Who can run it: a grant on the project whose role has read.

API: GET /api/v1/projects/{project}/integrations/{name}.

weikio get versions#

List an integration’s published versions, newest first. latest marks the newest version, and the last column lists the environments each version runs in.

weikio get versions <p>/<n>

Who can run it: a grant on the project whose role has read.

API: GET /api/v1/projects/{project}/integrations/{name}/versions, GET /api/v1/users/_emails?ids=.

Also written as weikio versions.

$ weikio get versions finance/erp-invoice-export

VERSION          CAMEL    CREATED                BY                 NOTE                DEPLOYED IN
1.1.0 (latest)   4.22.1   2026-09-16 14:31 UTC   anna@example.com   invoice mapper v2   -
1.0.0            4.22.1   2026-09-15 09:12 UTC   anna@example.com   -                   devtest, production

weikio describe version#

Read one published version with its digests and dependencies.

weikio describe version <p>/<n> <version>

Who can run it: a grant on the project whose role has read.

API: GET /api/v1/projects/{project}/integrations/{name}/versions/{version}, GET /api/v1/users/_emails?ids=.

weikio version create#

Build a new version of an integration on another Camel line. A Camel upgrade is a new version: this builds the integration’s current files again on another Camel line, and both versions can run side by side in different environments.

weikio version create <p>/<n> --camel-version V [--version X] [--note S]

Who can run it: a grant on the project whose role has author.

API: POST /api/v1/projects/{project}/integrations/{name}/versions.

Also written as weikio create version.

weikio version compare#

Show the file differences between two versions of an integration, as a unified diff. Each changed file prints as a unified diff, as diff -u writes it. The command exits 0 when the two versions have the same files and 2 when they differ.

weikio version compare <p>/<n> <from-version> <to-version>

Who can run it: a grant on the project whose role has read.

API: GET /api/v1/projects/{project}/integrations/{name}/versions/{version}, GET /api/v1/projects/{project}/integrations/{name}/source/files/{path}?version=.

weikio status#

Show where an integration runs and in what state. When a deployment is pending, the DETAIL column says why, such as no agent that may run the project or all matching agents draining.

weikio status <p>/<n> [--env E] [--watch]

Who can run it: a grant whose role has read in the environment.

API: GET /api/v1/projects/{project}/integrations/{name}/status, GET /api/v1/metrics/summary, GET /api/v1/traces/_related.

$ weikio status finance/erp-invoice-export

ENVIRONMENT   VERSION   STATE     AGENT         SINCE                  DETAIL
devtest       1.0.0     running   agent-fi-01   2026-09-15 09:14 UTC   -
production    1.0.0     running   agent-fi-02   2026-09-15 16:02 UTC   -

weikio logs#

Print the logs of an integration in one environment. -f follows new lines until Ctrl-C. --top-errors groups the window’s errors by exception and route, --histogram counts lines per interval and level, and --build prints a version’s build output.

weikio logs <p>/<n> [--env E] [-f|--follow] [--since 10m] [--from T --to T] [--level L] [--agent ID] [--correlation-id ID] [--query Q] [--limit N] [--before ID | --after ID] [--histogram [--interval 1h]] [--top-errors] [--build --version X]

Who can run it: any API key. The lines are narrowed to what your read grants open.

API: GET /api/v1/logs?whole=true&order=oldest, GET /api/v1/logs/tail?whole=true, GET /api/v1/logs/histogram, GET /api/v1/projects/{project}/integrations/{name}, GET /api/v1/projects/{project}/integrations/{name}/versions/{version}/build.

weikio invoke#

Send a message into a running route. The message goes into the running route through the agent, the way camel cmd send does it, so no port is opened. Any endpoint whose component accepts a message works, such as direct:, seda: and kamelet:. A timer, a scheduler or an HTTP listener doesn’t accept one, and the command says which endpoint to call instead. The reply shows the trace id, and weikio trace opens the message’s trace.

weikio invoke <p>/<n> [--env E] [--endpoint <uri>] [--body @file|S] [--header k=v ...] [--timeout 30s] [--agent NAME|ID] [-y]

Who can run it: a grant whose role has operate in the environment.

API: POST /api/v1/environments/{environment}/projects/{project}/deployments/{name}/invoke?agent=.

$ weikio invoke finance/erp-invoice-export --env devtest --endpoint direct:run-export

Target: https://hub.example, project finance (argument), environment devtest (--env)
200 replied in 1.9 s
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-03
{"exported":14}

To see this message's trace, run:
  weikio trace 4bf92f3577b34da6a3ce929d0e0e4736

$ weikio invoke finance/nightly-payroll --env devtest

Target: https://hub.example, project finance (argument), environment devtest (--env)
error: No endpoint of version '1.0.0' of 'finance/nightly-payroll' accepts a message.
       'quartz:payroll/nightly' doesn't accept a message.
       Add a direct: route that this route calls:
         - from: uri: quartz:payroll/nightly    steps: [{ to: "direct:run-nightly-payroll" }]
         - from: uri: direct:run-nightly-payroll  steps: [ ... ]
       Then invoke that route with:
         weikio invoke finance/nightly-payroll --env devtest --endpoint direct:run-nightly-payroll

$ weikio invoke finance/goods-in --env devtest

Target: https://hub.example, project finance (argument), environment devtest (--env)
error: No endpoint of version '1.0.0' of 'finance/goods-in' accepts a message.
       'platform-http:/goods-in' is an HTTP endpoint, which invoke can't send to. Call it on its agent's host (port 8080 by default), or through an API routed to it.

$ weikio invoke finance/orders --env devtest

Target: https://hub.example, project finance (argument), environment devtest (--env)
error: Version '1.2.0' of 'finance/orders' has 3 endpoints that accept a message. Choose one with --endpoint:
         direct:new-order                 route new-order   routes/orders.camel.yaml
         seda:retry                       route retry       routes/orders.camel.yaml
         kamelet:timer-source?message=go  route nightly     routes/nightly.camel.yaml
       Not listed: 'platform-http:/orders' is an HTTP endpoint, which invoke can't send to. Call it on its agent's host (port 8080 by default), or through an API routed to it.

weikio delete integration#

Delete an integration that isn’t deployed, with its versions and its own variables and secrets.

weikio delete integration <p>/<n> [-y]

Who can run it: a grant on the project whose role has author.

API: DELETE /api/v1/projects/{project}/integrations/{name}?dryRun=true, DELETE /api/v1/projects/{project}/integrations/{name}.

weikio rename integration#

Rename an integration of any type.

weikio rename integration <p>/<n> <new-name>

Who can run it: a grant on the project whose role has author.

API: PATCH /api/v1/projects/{project}/integrations/{name}.

weikio export#

Export the documents you can read as YAML for weikio apply. The output applies again unchanged with weikio apply, which makes it the way to put an installation’s configuration into Git. Secrets are exported without their values.

weikio export [--project P] [--env E] [--out-dir DIR]

Who can run it: a grant on the project whose role has read.

API: GET /api/v1/configuration/export?project=&environment=.

weikio get camel-lines#

List the Camel lines an integration may be built on.

weikio get camel-lines

Who can run it: any valid API key.

API: GET /api/v1/camel-lines.

weikio get kamelets#

List the kamelets a project may use.

weikio get kamelets [--project P]

Who can run it: a grant on the project whose role has read.

API: GET /api/v1/projects/{project}/kamelets/_usage.

weikio kamelets pull#

Write the project’s and the platform’s kamelets to a directory, for running with plain Camel. Use it to run an integration with plain camel run and the same kamelets the platform gives it.

weikio kamelets pull <dir> [--project P]

Who can run it: a grant on the project whose role has read.

API: GET /api/v1/projects/{project}/kamelets/_local.

weikio describe kamelet#

Print one kamelet.

weikio describe kamelet <p>/<n>

Who can run it: a grant on the project whose role has read.

API: GET /api/v1/projects/{project}/kamelets/{name}, GET /api/v1/projects/{project}/kamelets/_usage.

weikio delete kamelet#

Delete a kamelet no version references.

weikio delete kamelet <p>/<n> [-y]

Who can run it: a grant on the project whose role has author.

API: DELETE /api/v1/projects/{project}/kamelets/{name}.

In a pipeline#

Weik.io never reads your Git repository. A pipeline runs the weikio CLI with a key of its own and pushes each change to the hub, so the hub needs no Git credentials and no network path to your Git host. A repository with a shared folder and one folder per environment uses these jobs:

The job sets WEIKIO_SERVER, WEIKIO_API_KEY and WEIKIO_REASON, and the CLI records the repository, branch and commit on every document it writes. A secret’s value comes from the job and never from Git, so a step before the apply sets it with printf '%s' "$ERP_API_KEY" | weikio secret set finance/erp-api-key --env production -y.

Exit codes#

The commands on this page exit with the codes in the exit code table: 0 on success, 1 when the hub refuses a change, 2 for a usage error, 3 when the key is missing or not allowed, 4 when something isn’t found, 5 for a conflicting change, 6 when the hub can’t be reached and 8 when a document isn’t valid. weikio diff exits 0 when nothing would change, 2 when something would and 7 when a document or folder would be refused. weikio version compare exits 0 when two versions have the same files and 2 when they differ. weikio apply exits 7 when part of the set was applied and part refused, and weikio validate exits 8 when a check fails.

See also#

• Your first integration
• Integration folders and routes
• Versions and the developer loop
• Dependencies and kamelets
• Keep integrations in Git