ir command reference
ir is Infrared's command-line client. It calls the same API as the UI, so what you can do with it depends on your roles. Before Infrared exists on a cluster, ir install and ir restore reach the cluster through helm and kubectl by a named kubeconfig context, never the current one.
Every command has --help with its flags and examples. This page lists them and shows the ones you'll use most.
Get ir
Build ir from the infrared-cli repository: make install-local puts it at ~/.local/bin/ir, and make build makes binaries for macOS and Linux on amd64 and arm64. ir --version prints the version.
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 in Settings → API tokens, keep it in a file only you can read, and give it to ir on stdin:
ir login --server https://infrared.example.com/api --token-stdin < ~/.secrets/infrared-token
ir login --context <context> points ir at an install through its kubeconfig context instead, and ir open [<path>] signs a browser in with the saved token. See Use ir with an API token.
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 | Output format. Default table |
--server <url> | The API's URL. Default: from the config file |
--config <file> | The config file. Default $XDG_CONFIG_HOME/infrared/config.yaml |
| Exit status | Meaning |
|---|---|
0 | Done, or the state a wait was for was reached |
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 release wait, ir status --wait) ask again every 5 seconds and write each change to stderr, so the result on stdout stays clean for -o json.
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. Unless --no-hydrate, the architect hydrates it |
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. 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 every step's status |
ir agentworkflow list, get <name> | The org's AgentWorkflows |
ir agentrole list, get, edit, enable, disable, reset | The org's AgentRoles; get compares one with the catalog, edit opens its spec in $EDITOR, reset restores the catalog's spec and keeps whether it's enabled |
ir scheduling get, set --enabled=true|false | Whether the org's scheduled AgentWorkflowRuns run |
ir agent-steps get, set --placement jobs|pools [--fallback jobs|wait] | Where the org's agent steps run: as runner Jobs in the cluster (jobs, the default) or on its runner pools (pools); --fallback says what a step placed on the pools does while no pool is alive |
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
Releases
| Command | What it does |
|---|---|
ir release new --product <p> [--version <v>] [--commit <sha>] [--notes <text>] | Start a Release of the default branch's head, or of a commit. Only one Release of a Product is in progress at a time |
ir release list, get <name> | The org's Releases, newest first; one with its build, tag and each zone's pull request and health |
ir release promote <name> --zone <zone> [--wait] | Approve the promotion to a zone that is AwaitingApproval. --wait then waits until the zone runs it Healthy |
ir release wait [<name>] --for released|awaiting-approval | Wait for a Release's phase. --product <p> follows the Product's newest Release instead of a named one |
ir release wait <name> --zone <zone> | Wait until the Release runs Healthy in a zone |
ir release retry <name> | Start a Failed Release again from where it failed |
ir release new --product zippy
ir release wait --product zippy --for awaiting-approval --timeout 1h
ir release promote zippy-7kq2m --zone zippy-prod --wait
Products, orgs and clusters
| Command | What it does |
|---|---|
ir product list, get <name> | The org's Products |
ir product create [<name>] -f infrared.yaml [--zone <z>] | Create a Product from the file's products section: its repos and their starters, then the Product with its zones |
ir product zone add -f infrared.yaml, zone set -f infrared.yaml | Add the zones the file lists that the Product lacks, or set them to what it says |
ir product zones <product> | Each zone as it runs now: version, image, Release, sync and health, pods, smoke check, and a newer version on its way |
ir product links <product> | Every place to see a Product: its zones' addresses, status page, repos and latest release |
ir org list, get <name> | Orgs |
ir access-group list, set -f <file> | An org's access groups: who has which role, and replacing them from a YAML or JSON file, which holds a list of access groups or {accessGroups: [...]}. ir access-groups is the same command. For one release, the deprecated ir team and ir teams still work, and set -f still takes the old {teams: [...]} |
ir cluster list, get <name>, register <name>, remove <name> | The management cluster and workload clusters |
ir incident list | The org's incidents, open ones first |
ir license get, install | The license's state, and installing one |
ir status [--wait] | The Installation, the management cluster, the gitops repo and its sync waves |
Install, set up, back up and restore
| Command | What it does |
|---|---|
ir install --context <c> -f infrared.yaml [--setup] [--wait] | The one helm install of Infrared. --setup then runs the setup wizard, and --wait waits until every Application is Synced and Healthy. It refuses a cluster that already has Infrared, and a backup prefix another install already writes to |
ir setup run -f infrared.yaml, status, wait | Run the setup wizard from a file, show its progress, or wait for it. See Scripted setup |
ir backup status, list, get <stamp> | Where backups go and the newest point; the newest 24 backups; 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 set, with a real write |
ir backup key new | Make the age key pair backups are encrypted to, and print its public half |
ir backup pull <stamp> --out <dir> -f infrared.yaml [--full] | Download a backup straight from the bucket, for a copy outside it |
ir restore --backup-artifact <stamp or file> --context <c> -f infrared.yaml | Restore an install from a backup onto new servers |
See Back up and restore.
ir local runs a whole Infrared on a Mac, in a container machine. ir local --help lists its commands. When ir login has signed you in to an Infrared, ir local up sends the stack's metrics there by itself, under the platform <your GitHub login>-<stack>, with nothing to set up; --no-telemetry leaves them out.