agent

initializ agent groups the commands that scaffold, inspect, and manage agents. The deploy subcommand has its own page; this page covers init, list, get, logs, and secrets set.

All subcommands accept the global flags. The commands that talk to the platform (list, get, logs, secrets set) operate in the workspace resolved from --workspace / INITIALIZ_WORKSPACE_ID / the config file / the token's workspace scope; init runs entirely locally and needs no credentials.

Resolving agents by name or id

Commands that take <name-or-id> accept either form: values starting with agt- are treated as agent ids and fetched directly; anything else is matched by exact name against the workspace's agent list. An unmatched name exits with code 4 (not found).

initializ agent list

Lists the workspace's agents.

initializ agent list

ID       NAME           STATUS   MANAGED BY  IMAGE
agt-42   support-agent  running  ci          registry.initializ.ai/acme/support-agent:sha-1a2b3c4
agt-57   triage-agent   running  platform

MANAGED BY is ci for agents deployed via initializ agent deploy and platform for agents built in the console. IMAGE is the last deployed image tag (empty when the agent has no build record). agent list has no flags of its own; use -o json for the full records.

initializ agent get

Shows one agent.

initializ agent get <name-or-id>

initializ agent get support-agent

ID           agt-42
NAME         support-agent
STATUS       running
MANAGED BY   ci
MODEL        openai/gpt-4o
LAST DEPLOY  success
IMAGE        registry.initializ.ai/acme/support-agent:sha-1a2b3c4

MODEL is provider/model from the agent's forge configuration. When the last deploy failed, an ERROR row shows the server-side error. agent get has no flags of its own.

initializ agent logs

Prints the deploy progress log — the platform's streamed create/deploy log for the agent — or, with --runtime, the agent pod's own logs.

initializ agent logs <name-or-id> [--runtime]

agent logs flags

agent logs examples

# Why did the last deploy fail?
initializ agent logs support-agent

# What is the running agent printing?
initializ agent logs support-agent --runtime

Logs are written verbatim to stdout.

initializ agent secrets set

Rotates secret values on a deployed agent. The given keys are updated in the agent's Kubernetes Secret and the pods are rolled — no redeploy needed. Values are never persisted by the platform.

initializ agent secrets set KEY=VALUE [KEY2=VALUE2 …] --agent <name-or-id>

A bare KEY (no =VALUE) reads the value from the CLI's own environment, keeping secrets out of argv and shell history. A bare key that is not set in the environment fails with exit code 2.

agent secrets set flags

agent secrets set examples

# Value taken from the CI/shell environment (recommended):
export OPENAI_API_KEY=sk-…
initializ agent secrets set OPENAI_API_KEY --agent support-agent

# Multiple keys, explicit values:
initializ agent secrets set SLACK_BOT_TOKEN=xoxb-… WEBHOOK_SECRET=whsec-… --agent agt-42

updated OPENAI_API_KEY on support-agent; pods are rolling

The confirmation goes to stderr. With -o json, a machine-readable result is also written to stdout:

{
  "agent_id": "agt-42",
  "updated": ["OPENAI_API_KEY"]
}

initializ agent init

Scaffolds a deployable claude-agent: the deploy spec plus an A2A (Agent2Agent) executor stub. Runs entirely locally — no platform credentials needed.

initializ agent init [--name <agent>] [--provider anthropic|openai] [--dir <path>]

Two files are written (existing files are skipped unless --force):

• initializ-deploy.yaml — the deploy spec, with agent.type: claude-agent and A2A enabled by default (auth: bearer), plus an INITIALIZ_ENFORCEMENT: audit_only env entry so the agent starts in observe-only mode. See the claude-agent runtime for the full schema.
• a2a-executor.ts — an @initializ/a2a-kit executor stub with one skill; fill in its run(). When the project keeps sources under src/ (a src/ directory exists, or tsconfig.json declares a src rootDir), the stub is placed at src/a2a-executor.ts so tsc emits it to dist/a2a-executor.js.

If a package.json is present, the "initializ": { "a2a": "./dist/a2a-executor.js" } pointer is wired in automatically (formatting preserved; if the insertion would produce invalid JSON, nothing is written and the command prints the snippet to add manually). Once the executor's skills are implemented, the governed image serves the Agent Card and JSON-RPC endpoint and routes tasks to them.

The agent name must be a valid DNS-1123 label (lower-case letters, digits, and hyphens; max 63 characters; no leading or trailing hyphen) — it becomes the agent's Kubernetes name. An invalid name exits with code 2, as does a --provider other than anthropic or openai.

agent init flags

agent init example

initializ agent init --name code-reviewer --provider anthropic

After scaffolding:

1. npm install @initializ/a2a-kit
2. Implement run() in the executor stub (point it at your handler).
3. Build and push the governed image in CI, then deploy: initializ agent deploy -f initializ-deploy.yaml --image <ref>