CLI reference

origamy deploys and operates a self-hosted data plane on a Kubernetes cluster or a plain Docker host. It is a single static binary for macOS and Linux (amd64 and arm64).

Installing the CLI

The Connections page prints a one-liner that installs the CLI and runs deploy in one go:

sh -c "$(curl -fsSL https://v1.origamy.io/install.sh)" deploy --token dpe_xxx

The script fetches the latest GitHub release, verifies the binary against the release’s SHA256SUMS, and verifies SHA256SUMS against a detached Ed25519 signature (SHA256SUMS.sig) using the public keys embedded in the script. The signature check needs an openssl that can handle Ed25519: OpenSSL 3 on Linux, or Homebrew’s openssl@3 on macOS (the LibreSSL that macOS ships cannot, so there the script says so and continues with the checksum alone). Where the signature can be checked, a failure aborts the install. Re-running the one-liner updates the CLI in place.

Commands

Command	What it does
`origamy deploy --token dpe_…`	Enrols the data plane and installs it (Helm on Kubernetes, Compose on Docker).
`origamy upgrade`	Moves an install to a newer release; also toggles optional services.
`origamy rollback [--to N]`	Kubernetes: rolls back to the previous (or a named) Helm revision.
`origamy status`	Installed version, whether a newer one is published, service health.
`origamy uninstall [id]`	Removes the data plane: the Helm release and namespace, or the Compose project and its volumes.
`origamy version`	Prints the CLI version.

`origamy deploy`

origamy deploy --token dpe_xxx [--enable-ai] [--datastore-auth] [--version 0.1.17]

Enrollment. The dpe_ token carries only a one-time handle. The CLI generates an EC P-256 keypair, sends a certificate signing request to the control plane over HTTPS, and receives the real credential, the tunnel address, and — when the control plane has a certificate authority configured — a signed client certificate for the tunnel. The private key is written only to your side (a Secret, or ./certs/ next to the compose file). Tokens are single-use and expire after 72 hours, so a deploy that fails after enrolling needs a fresh token from the Connections page.

Target detection. kubectl cluster-info succeeding means Kubernetes; otherwise a working docker info means Docker Compose.

On Kubernetes

Prompts: deployment size (Starter / Standard / Production presets), the AI engine (unless --enable-ai was given), embedded or external ClickHouse (release 0.1.19 and newer; see below), and how to expose the event endpoint:

LoadBalancer — a cloud load balancer on port 8081, requested as internet-facing (the AWS Load Balancer Controller defaults to internal).
Ingress — HTTPS on your own domain via your ingress controller (asks for the class, default nginx).
Internal — ClusterIP only; expose it later.

External ClickHouse

From data-plane release 0.1.19, deploy can connect your own ClickHouse instead of running one in the cluster. Earlier releases always get the bundled one: their charts cannot authenticate to another server or create its schema, so the CLI does not offer the choice there. Choosing External asks for:

Host — a host name or IPv4 address. host:port and a pasted URL such as https://abc.eu-west-1.aws.clickhouse.cloud:9440 work too.
TLS — whether the server requires TLS on the native port (default yes; ClickHouse Cloud and most managed services do).
Port — the native protocol port: 9440 with TLS, 9000 without. 8123 and 8443 are ClickHouse’s HTTP interface, which the data plane cannot use, so they are refused.
User (default default) and password, typed with echo off. Leaving the password empty asks you to confirm a connection without one.

The chart places the password verbatim in the services’ connection URL, so it may contain only letters, digits and -._~!$&'()*+,;=:@. The CLI rejects anything else before the token is spent.

Nothing contacts the server from your machine, since it may only be reachable from inside the cluster. During install the chart’s clickhouse-init Job creates the events database and its tables there, so the user needs CREATE DATABASE, CREATE TABLE, INSERT and SELECT. The chart’s NetworkPolicy opens egress to that port; see Bring your own ClickHouse to narrow it.

It then creates the origamy-dp namespace and stores every secret as a pre-created Kubernetes Secret, never through helm --set (which would persist them in release history):

Secret	Contents
`origamy-byod-token`	the data-plane bearer token (`auth-token`)
`origamy-byod-identity`	mTLS client certificate, private key and CA chain — only when the control plane issued one
`origamy-clickhouse`	the external ClickHouse password (`clickhouse-password`) — only for an external ClickHouse with a password

Finally it runs helm upgrade --install odp oci://ghcr.io/qubelylabs/charts/origamy-data-plane with the chart version it pins (--version overrides it), waits for the pods, and prints the event endpoint. --datastore-auth adds datastores.auth.enabled=true, and the chart generates Redis, NATS and ClickHouse passwords into in-cluster Secrets.

The CLI refuses --enable-ai on a chart older than 0.1.16 and --enable-predictor on a chart older than 0.1.17: Helm silently ignores values a chart does not know, so an older chart would report the feature enabled while deploying nothing. For the same reason it offers an external ClickHouse only from chart 0.1.19.

On Docker

Prompts: deployment size (Starter / Standard), whether to run the engagement services (Postgres + workflow-engine — journeys, broadcasts, human tasks; default yes), the AI engine (unless --enable-ai was given), and an optional domain for an HTTPS event endpoint.

It writes ./origamy-dp-<id>/ containing:

docker-compose.yml, clickhouse-init.sql, clickhouse-users.xml and (with a domain) Caddyfile, downloaded from your control plane’s /byod/*.
.env (mode 0600): the control-plane addresses, your data-plane id and token, DP_IMAGE_TAG pinned to the release, COMPOSE_PROFILES for the services you chose (full, agentic, ingress), INGEST_DOMAIN, and freshly generated passwords for Redis, NATS, ClickHouse and Postgres. With the AI engine on, it also generates the engine’s encryption key (ORCH_KEK) and internal API token.
certs/ with the mTLS identity, when one was issued.

Re-running deploy in the same directory reuses the passwords already in .env — rotating them would lock the datastores out of their own data — and carries the AI encryption key forward even when the engine is off, so a later --enable-ai can still read stored LLM credentials.

`origamy upgrade`

origamy upgrade                        # Kubernetes: latest published chart; Docker: this CLI's release
origamy upgrade --version 0.1.17       # a specific release
origamy upgrade --channel edge         # track the moving :main images
origamy upgrade --enable-ai            # or --disable-ai        (Kubernetes and Docker)
origamy upgrade --enable-predictor     # or --disable-predictor (Kubernetes only)
origamy upgrade --set key=value        # extra chart values     (Kubernetes only)

On Kubernetes it resolves the latest chart from the registry, pins that version globally and per service (--reuse-values on its own can leave a service on a stale image tag), then restarts the Deployments so they re-pull; datastore StatefulSets are never touched. A feature toggle re-applies your values from a clean export instead of --reuse-values, so a chart that gained new defaults (the predictor, say) renders correctly on a release installed before it existed. The same chart-version gate as deploy applies to the toggles, and a plane on an external ClickHouse cannot be moved to a chart older than 0.1.19.

On Docker it sets DP_IMAGE_TAG in .env — to the release the CLI was built for, or the version you name, or main for --channel edge — pulls, and runs docker compose up -d --remove-orphans. --enable-ai adds the agentic profile (generating the engine’s secrets on first use) and --disable-ai removes it; the encryption key is kept.

`origamy rollback`

Kubernetes only: helm rollback to the previous revision, or --to N. Docker installs move between releases with origamy upgrade --version.

`origamy status`

Shows the installed chart or image tag, the active compose profiles, whether a newer release is published, and per-service health with a one-line diagnosis for pods that are not ready.

`origamy uninstall`

Kubernetes: helm uninstall odp and deletes the origamy-dp namespace. Docker: docker compose down -v in ./origamy-dp-<id>/ (pass the id) and removes the directory. Both ask for confirmation unless --yes is given. Run it before deactivating the workspace so the plane stops trying to reconnect.

Releases and channels

Chart and images share one version per data-plane release. A fresh deploy pins the release built into the CLI (currently 0.1.17); upgrade moves you forward deliberately. --channel edge tracks the mutable :main images instead — fine for a dev plane, not recommended for production, since a restart can pull a different build.

What leaves your network

Only the outbound tunnel and config polling. Datastore passwords, the AI encryption key and the mTLS private key are generated on your side and never transmitted. The enrollment handle is the one credential that travels, once, over HTTPS — the CLI refuses to redeem it over a plaintext URL.

Troubleshooting

Message	Meaning
`Invalid or unusable enrollment token`	The token was already redeemed or has expired. Generate a new one from the Connections page.
`the AI engine needs chart 0.1.16 or newer` / `the predictor needs chart 0.1.17 or newer`	You targeted an older chart with a toggle it cannot deploy. `origamy upgrade` first, or pass `--version`.
`This data plane uses an external ClickHouse, which needs chart 0.1.19 or newer`	`upgrade` targeted a chart that cannot reach your ClickHouse. Pass `--version 0.1.19` or newer.
`The password contains …, which the data plane cannot carry`	The external ClickHouse password has a character the connection URL cannot hold. Set a password using only the characters listed under External ClickHouse.
Pods crash-loop after choosing External ClickHouse	Services wait until the schema exists on your server. `kubectl logs -n origamy-dp -l app.kubernetes.io/component=clickhouse-init --tail=20` shows why the schema Job cannot connect: host, port, TLS or credentials.
`Your control plane does not serve clickhouse-users.xml`	The control plane predates this CLI’s Docker bundle. Upgrade it, or deploy with an older CLI.
`A container image could not be pulled`	The pinned release is not published yet or the registry is unreachable; `origamy upgrade --version` to a published one.