ir command reference
ir is Infrared's command-line client. It calls the same API as the UI, so you can do with it exactly what your roles let you do in the browser. Use it when you want a script, a terminal or an agent to drive Infrared: open an issue, start a Change, wait for a deployment to reach production, cut a release.
Every command has --help with its flags and examples. This page lists them all and shows the ones you will use most.
Get ir
Build ir from a checkout of the infrared-cli repository:
make install-local # builds ir and puts it at ~/.local/bin/ir
ir --version
make install-local tells you if ~/.local/bin is not on your PATH, and gives you the line to add to your shell profile. Run it again after you pull to update. make build makes binaries for macOS and Linux, on amd64 and arm64, for other machines.
Sign in
ir never takes a token or a password as an argument, because shell history and the process list keep arguments. Mint an API token on the You page, keep it in a file only you can read, and pass it on stdin:
ir login --server https://infrared.example.com/api --token-stdin < ~/.secrets/infrared-token
| Command | What it does |
|---|---|
ir login --server <url> --token-stdin | Check an API token and save it, with the server, in the config file |
ir login --context <context> | Check the token ir saved against the install's own address, which ir reads from the cluster through that kubeconfig context, and save the address. Use it after ir install --setup or ir setup run |
ir login --server <url> --email <root> [--password-file <file>] | Break glass: sign in once as the root user and mint an API token for this machine. The password comes from a file only you can read, or a prompt. Infrared shows every use in Access → Break glass |
ir login --server <url> --setup-token-stdin | Use the one-time setup token, before the root user exists |
ir open [<path>] [--print] [--context <c>] | Open Infrared in your browser, signed in as the token's owner, at a page such as /access. The sign-in link works once, within 60 seconds. --print prints the link instead, so keep it out of logs and chats |
Global flags and exit codes
| Flag | What it does |
|---|---|
--org <org> | The org to act on. Default: the configured org, else the platform org |
-o, --output table|json|yaml | The output format. Default table |
--server <url> | The API's address. Default: the one in the config file |
--config <file> | The config file. Default $XDG_CONFIG_HOME/infrared/config.yaml |
-v, --version | Print the version |
| Exit status | Meaning |
|---|---|
0 | Done, or the wait reached the state it was waiting for |
1 | An error, or a wait that ended in a failed state |
2 | A mistake in the command line or in infrared.yaml |
124 | A wait that ran out of --timeout |
Commands that wait (--wait, ir deployment wait, ir status --wait) check again every 5 seconds and write each change to stderr. The result goes to stdout, so -o json stays clean for your scripts.
Ask for and follow Changes
| Command | What it does |
|---|---|
ir issue create --product <p> --title <t> [--body <b>] [--repo <r>] [--no-hydrate] | Open an issue on a Product repo, in Backlog. A title is enough: unless you pass --no-hydrate, the architect adds acceptance criteria, design notes, a verification plan and an estimate, then moves it to Arch reviewed |
ir issue list --product <p> | The open issues on a Product's repos, by backlog column |
ir run start --workflow <w> --product <p> [--issue <n>|<repo>#<n>] [--pull-request <n>] [--repo <r>] | Start an AgentWorkflowRun, usually for one issue, or to review a pull request that already exists. The AgentWorkflow must be enabled, and every AgentRole step spends model tokens |
ir run list [--product <p>] | The org's AgentWorkflowRuns, newest first |
ir run get <run> | One run and the status of every step |
ir run retry <run> --step <step> [--guidance <text>] | Run a DeadLettered or Failed step again, and every step after it. --guidance answers the step's questions or steers it: the agent sees it, with your name, on this attempt and later ones |
ir run cancel <run> [--reason <text>] | Cancel a run that hasn't finished. The reason shows on the run |
To start the same Change as Ask for a change on a Product's page:
ir issue create --product zippy --title "Show the build commit on /version" --no-hydrate
ir run start --workflow change-quick --product zippy --issue 12
ir run get change-quick-zippy-12-abcde -o yaml
When an agent stops and asks a question, answer it and send the step back to work:
ir run retry change-quick-zippy-12-abcde --step builder --guidance "Keep the /changelog route."
Deployments
A deployment is one version of a Product on its way through its environments. The API calls it a Release, and its paths keep that name.
| Command | What it does |
|---|---|
ir deployment new --product <p> [--version <v>] [--commit <sha>] | Start a deployment of the default branch's head, or of a commit. Infrared waits for the build, tags the next patch version unless --version names one, and promotes it zone by zone. A Change merged by an AgentWorkflowRun deploys on its own; use this for anything else. Only one deployment of a Product runs at a time |
ir deployment list [--product <p>] | The org's deployments, newest first |
ir deployment get <name> | One deployment: who asked for it, its build and kpack's steps, its tag, and each zone's pull request, health and hold |
ir deployment promote <name> --zone <zone> [--wait] | Approve the promotion to a zone that is AwaitingApproval. Infrared records your approval, then opens and merges the zone's pull request |
ir deployment go <name> --zone <zone> [--wait] | Go now: end the release guard's hold in a zone that is Holding. The guard still reads the error budgets and runs the checks once more before it moves on, so the zone can still fail. Infrared records who went ahead |
ir deployment build-log <name> [--tail <n>] | The log of the deployment's kpack build: the last lines of each step (500 unless --tail says otherwise, at most 5000) |
ir deployment wait [<name>] --for released|awaiting-approval | Wait for a deployment to reach that phase. --product <p> follows the Product's newest deployment instead of a named one |
ir deployment wait <name> --zone <zone> | Wait until the deployment runs Healthy in a zone |
ir deployment retry <name> | Start a Failed deployment again from where it failed. What it already did stays; failed zones start over |
--wait on promote and go waits as ir deployment wait --zone does. A Failed zone or deployment ends any wait with exit 1.
ir deployment new --product zippy
ir deployment wait --product zippy --for awaiting-approval --timeout 1h
ir deployment promote zippy-7kq2m --zone zippy-prod --wait
Scripts written before ir deployment existed can still run ir release new, promote, go, build-log, retry and wait. They work as before and print a note on stderr naming the ir deployment command to use.
Releases
A release gathers the deployments of a Product that reached production since the last release under one version, with release notes for engineers and a post for everyone else. The API calls it a ReleaseCut. See Cut a release.
| Command | What it does |
|---|---|
ir release list [--product <p>] | The org's releases, newest first |
ir release get <name> | One release: its version and title, its changes by kind, and the deployments it covers |
ir release cut --product <p> [--major | --track] [--title <t>] [--notes-file <f>] [--post-file <f>] [--yes] | Cut a release. ir shows you the draft and asks before it cuts, unless you pass --yes. The version is the next minor of the one in production, or the next major with --major. --track announces the version in production as its major.minor track instead. --title, --notes-file and --post-file replace the draft's; the files are Markdown, or - for stdin. Only an org-admin can cut a release |
ir release cut --product zippy
ir release get zippy-1-7-0
Products
| Command | What it does |
|---|---|
ir product list, ir product get <name> | The org's Products, or one |
ir product create [<name>] -f infrared.yaml [--zone <z>] | Create a Product from the file's products section, as Create product does: each repo with its starter, then the Product and its zones. With build: true, Infrared also writes the build, a chart and the zones' files, and starts the first deployment |
ir product zone add <product> -f infrared.yaml [--zone <z>] | Add the zones the file lists that the Product doesn't have yet. Needs org-admin |
ir product zone set <product> -f infrared.yaml [--zone <z>] | Set each zone the file lists to exactly what the file says. Needs org-admin |
ir product zones <product> | Each zone as it runs now: version, image, the deployment that put it there, sync and health, ready pods, the last smoke check, and any newer version on its way |
ir product links <product> | Every place to see a Product: each zone's address and who can open it, the status page, and its repos and latest release on GitHub |
ir incident list [--product <p>] [--open] | The org's incidents, open ones first |
Agents
| Command | What it does |
|---|---|
ir agentrole list [--category <c>] [--enabled=true|false] | The org's AgentRoles |
ir agentrole get <name> | One AgentRole, and how it differs from the catalog |
ir agentrole edit <name> | Open the AgentRole's spec in $VISUAL or $EDITOR. If someone changed it while you were editing, nothing is written and your edit is kept in a file you can apply again |
ir agentrole enable <name>, disable <name> | Let an AgentRole run, or stop it |
ir agentrole reset <name> | Put back the catalog's spec. Whether the AgentRole is enabled stays as it is |
ir agentworkflow list, get <name> | The org's AgentWorkflows |
ir scheduling get | Whether the org's scheduled AgentWorkflowRuns are on |
ir scheduling set --enabled=true|false [--time-zone <tz>] | Turn scheduled runs on or off. Each AgentWorkflow with a cron trigger then runs once per Product at its times, read in the time zone you give (UTC by default). Every run spends model tokens. Needs org-admin |
Orgs, access and clusters
| Command | What it does |
|---|---|
ir org list, ir org get <name> | Orgs |
ir access-group list | The org's access groups: who holds which role |
ir access-group set -f <file> | Replace every access group of the org with the ones in a YAML or JSON file. Start from ir access-group list -o yaml. Needs org-admin |
ir cluster list, ir cluster get <name> | The management cluster and workload clusters |
ir cluster register <name> (--in-cluster | --kubeconfig <file>) [--flavor k3s|eks] [--provider <p>] [--region <r>] | Register a workload cluster: Infrared checks it, registers it with Argo CD and adds its app-of-apps to the platform org's gitops repo. --in-cluster places zones on the management cluster itself. Platform admins only |
ir cluster remove <name> | Remove a workload cluster. Zones on it stop deploying. Platform admins only |
ir access-groups is the same command as ir access-group.
Install, set up, back up and restore
Before Infrared runs on a cluster, ir install and ir restore reach it through helm and kubectl by a kubeconfig context you name, never the current one.
| Command | What it does |
|---|---|
ir install --context <c> -f infrared.yaml [--license <file>] [--setup] [--wait] | The one helm install of Infrared. Secrets reach helm from files or commands, never as arguments. --license installs your license as it goes. --setup then runs the setup wizard, and --wait waits until every Application is Synced and Healthy. It refuses a cluster that already has Infrared |
ir setup run -f infrared.yaml [--context <c>] | Run the setup wizard from the file's setup section. Steps already done are left alone. See Scripted setup |
ir setup status, ir setup wait | The setup wizard's progress, or wait until the install is Ready |
ir backup status | Where backups go, how they are made, and the newest point |
ir backup list, ir backup get <stamp> | The newest 24 backups, or one backup's manifest |
ir backup now [--wait] | Make a backup now, then the mirror run that makes it a point |
ir backup destination set -f infrared.yaml, destination check | Set where backups go, or check the destination with a real write |
ir backup key new <install> [--out <file>] | Make the age key pair backups are encrypted to. ir prints only the public half; keep the private one with your other secrets |
ir backup pull <stamp> --out <dir> -f infrared.yaml [--full] | Download a backup straight from the bucket, to keep a copy elsewhere. It works even after the install is gone |
ir restore --backup-artifact <stamp or file> --context <c> -f infrared.yaml | Restore an install from a backup onto new servers |
See Install Infrared and Back up and restore.
Status and license
| Command | What it does |
|---|---|
ir status [--wait] | The Installation's phase and version, the management cluster, the gitops repo and its sync waves, and resource counts |
ir license get | The license's state and what it grants |
ir license install <file|-> --email <platform admin> | Check a license and install it. The API takes it only from a platform admin's session, so ir asks for the password and signs in for this one call. See Licensing |
Connect an MCP client
Some MCP servers on an install sit behind Infrared's own sign-in, such as the code index at <your Infrared address>/mcp/code. ir mcp signs this machine in to one, for scripts and MCP clients that can't sign in on their own. Claude Code doesn't need it: it signs in by itself. See Connect an MCP client.
| Command | What it does |
|---|---|
ir mcp login [<address>] | Sign in through the browser with Google. Infrared lets you in if you hold a role in the platform org. With no address, ir uses the code index of the install it is signed in to |
ir mcp token [<address>] [--header] | Print an access token for that server into a pipe or a file, never to the terminal. --header prints it as the Authorization header an MCP client's headers helper expects |
ir mcp status | The sign-ins this machine keeps, and when each ends |
ir mcp logout [<address>] | Forget a sign-in |