CLI

The initializ CLI for CI pipelines — deploy CI-built agent images, rotate agent secrets, and inspect deploys from your pipelines.

The initializ CLI deploys forge agents whose images are built by your own CI to the initializ AI Platform. The platform never accesses your git repository — the CLI runs inside the CI checkout, reads forge.yaml, skill metadata, and forge build output, and sends the platform everything it needs alongside the image reference.

CI job:  forge build  →  docker build+push (workspace registry)  →  initializ agent deploy --wait

Agents deployed this way are CI-managed on the platform: skills, model provider, channels, policies, and guardrails cannot be edited in the console (the repo owns them; the platform returns 403 on such edits). Environment variables and secrets remain editable — via initializ agent secrets set or the console.

auth — login and whoami

Store a token locally or preflight-verify the CI token.

agent deploy

The CI deployment flow: deploy spec, forge.yaml, build output, --wait.

agent — list, get, logs, secrets

Inspect deployed agents and rotate their secrets.

Install

Binaries are published as goreleaser artifacts on the GitHub releases of initializ/cli-next (multi-arch archives + checksums):

curl -fsSL https://github.com/initializ/cli-next/releases/latest/download/initializ_linux_amd64.tar.gz \
  | tar xz && sudo mv initializ /usr/local/bin/

Container-native CI can use the released image ghcr.io/initializ/cli-next:<version> instead of installing a binary.

Authentication

An org or workspace admin mints a workspace-scoped access token (role developer or workspace_admin) via the console. The CLI authenticates every request with that token.

Configuration is resolved with precedence flag > environment variable > config file — for every setting, everywhere.

In CI, skip auth login entirely and set environment variables:

Env var	Meaning
`INITIALIZ_API_URL`	Platform API base URL
`INITIALIZ_TOKEN`	The access token (store it as a CI secret)
`INITIALIZ_ORG_ID`	Organization id (`org_…`)
`INITIALIZ_WORKSPACE_ID`	Workspace id (`ws_…`); optional if the token is workspace-scoped
`INITIALIZ_AUTH_URL`	Override for the token-verification base URL — only needed when token verification is not served behind the same gateway as the rest of the platform API

Tokens are revocable server-side. initializ auth whoami verifies the token (signature and revocation) — use it as a pipeline preflight so a revoked token fails fast with exit code 3.

On a laptop, initializ auth login writes the resolved configuration to ~/.initializ/config.yaml (created with 0600 permissions because it holds the token). A missing config file is never an error — env vars and flags can carry the whole configuration (CI mode).

Global flags

These persistent flags are available on every command:

Flag	Shorthand	Default	Description
`--api-url`			Platform API base URL (env `INITIALIZ_API_URL`)
`--auth-url`			Override for the token verifier base URL (env `INITIALIZ_AUTH_URL`)
`--token`			Platform access token (env `INITIALIZ_TOKEN`)
`--org`			Organization id (env `INITIALIZ_ORG_ID`)
`--workspace`			Workspace id (env `INITIALIZ_WORKSPACE_ID`)
`--output`	`-o`	`text`	Output format: `text` or `json`
`--quiet`	`-q`	`false`	Suppress progress output

With -o json, exactly one JSON document is written to stdout — progress and log lines go to stderr — so initializ … -o json | jq is always safe.

Exit codes

The CLI has a fixed exit-code contract that CI pipelines can script against:

Code	Meaning
`0`	Success (with `--wait`: the rollout finished)
`1`	Unexpected error
`2`	Usage / spec validation error (bad YAML, unset `${VAR}` reference, missing required env var)
`3`	Authentication failure (invalid or revoked token; HTTP 401/403)
`4`	Not found (agent or workspace)
`5`	Deploy failed server-side (`--wait` observed a `failed` status)
`6`	`--wait` timed out

initializ version

Prints the CLI version, stamped at release time:

initializ version

initializ v0.3.0 (commit 1a2b3c4, built 2026-07-01)

Development builds print initializ dev (commit none, built unknown).

CLI