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 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 and sends the platform everything it needs alongside the image reference. For the default forge runtime it reads forge.yaml, skill metadata, and forge build output; for the claude-agent runtime (a governed Claude Agent SDK image) there is no forge.yaml — the deploy spec alone describes the agent.

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 — init, list, get, logs, secrets

Scaffold a claude-agent, inspect deployed agents, and rotate their secrets.

Install

Binaries are published on the GitHub releases of the public initializ/cli repository (multi-arch archives + checksums):

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

On macOS and Linux, Homebrew works too — the formula lives in the initializ/homebrew-tap tap:

brew install initializ/tap/initializ

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`	Base URL for server-side token verification (used by `auth login` / `auth whoami`). Omit when a single gateway routes both the deploy API and token verification on the `INITIALIZ_API_URL` host

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.

The root command also accepts --version, which prints the same line as initializ version.

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 prints the same line:

initializ version

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

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

CLI