Official command-line client for Avrea. avr brings runs, jobs, logs, and workflow control into your terminal.
AVR is a native executable for macOS on Apple Silicon, Linux AMD64/ARM64, and Windows AMD64. See installation and updates for platform requirements and upgrade details.
brew install avrea-com/tap/avrIf Homebrew reports an untrusted existing tap, trust the AVR formula and retry:
brew trust --formula avrea-com/tap/avrThe tap is updated separately from GitHub and PyPI; brew info avrea-com/tap/avr
shows the version currently available through Homebrew.
Use mise's built-in GitHub backend:
mise use -g github:avrea-com/cli@latest
mise exec github:avrea-com/cli@latest -- avr --versionOmit -g to configure AVR in the current project's mise.toml instead.
uv tool install avr-cliThe package manager uses Python for installation; the installed avr
executable runs without Python.
You can also use pipx install avr-cli, or install with
python -m pip install avr-cli inside a virtual environment.
Download the shell installer (Linux/macOS), PowerShell installer (Windows), or an archive from GitHub Releases. See native installation for version pins, checksum verification and PATH setup.
Use the same method you installed with:
brew upgrade avr # Homebrew
uv tool upgrade avr-cli # uv
pipx upgrade avr-cli # pipx
mise upgrade github:avrea-com/cli # mise (tracking latest)Run avr --version to verify which executable your shell is using. AVR may
notify you about updates, but does not install them automatically.
git clone git@github.com:avrea-com/cli.git
cd cli
make go-build
./build/go/avr --versionSource builds require the Go toolchain specified in go.mod and uv
(for packaging tools). Run
make test for native and tooling tests, and make lint for both languages.
Release artefacts (the native archives and PyPI wheels) carry keyless SLSA build provenance signed via Sigstore. Verify a downloaded artefact against this repository with the GitHub CLI:
gh attestation verify ./path/to/downloaded-archive --repo avrea-com/cliA successful check confirms the artefact was built by this repository's release workflow and has not been tampered with.
Browser-based login (recommended):
avr auth loginOn a remote machine, VM, or terminal without a browser:
avr auth device-loginOpen the displayed link on your laptop or phone, or scan the terminal QR code.
Confirm the code and approve the request. The CLI waits for approval and saves
the credential on the machine where you ran the command. Use --no-qr to hide
the QR code; the sign-in link is always displayed. QR output is omitted when
piped or when the terminal cannot display it. Device login requires support
on your Avrea server; avr auth login keeps its existing browser flow.
Show who you are and where you're pointing:
avr auth status
avr config # combined: host, auth, active org, default repo, all with sourcesLog out (revokes the active API key on the server):
avr auth logoutFor non-interactive environments (CI, scripts), set a token via env var instead. See Configuration.
Inside any git checkout of an Avrea-connected repository:
avr run list # uses git remote to scope the query
avr run view <run-id> # full run with jobs
avr run view <run-id> --log-failed # jump straight to failed-step outputAuto-detection means most commands "just work" without --repo. Outside a git tree (or to override), pass --repo org/name or --repo rep-xxx.
Clone from a nearby Git mirror
avr repo clone foo/faa
avr repo clone foo/faa my-checkout --depth 1 --branch main
avr repo clone foo/faa --placement https://git.fi.a.avrea.ioAvrea uses a single available placement directly. With multiple placements,
it picks the first mirror that responds successfully from your machine.
--placement accepts an advertised mirror URL or hostname to select one
explicitly. Give the owner/repository name or an Avrea repository ID (rep-...).
Requires Git 2.31 or newer. The repository must already have Git mirroring
enabled and a usable placement.
origin stays on the selected read-only mirror. The clone installs a
repository-local credential helper so ordinary git fetch and git pull
obtain fresh Git tokens through your Avrea login. Push changes to the source
repository using a separate remote, for example:
git remote add upstream git@github.com:foo/faa.git
git push upstream HEADTokens normally last one hour; scoped API keys are limited to ten minutes or
their remaining lifetime. Git tokens are never saved in the remote URL or
repository configuration. Keep avr installed and logged in for later Git
operations; the helper continues to use the API host used for the clone.
Create a mirror at a location
avr repo mirror locations
avr repo mirror create foo/faa --location gsc-fi
avr repo mirror create group/subgroup/project --source gitlab --location gsc-fi
avr repo mirror status --repo group/subgroup/project --source gitlab--source defaults to github; gitlab supports nested group names. The
repository must already be connected to your Avrea organization. Use --org
to select an organization. Mirror management requires the organization's
Git-mirror feature and an admin role.
--location accepts a cluster ID, datacenter ID, or unique name from locations.
The command enables mirroring and adds the placement, preserving existing
placements. Sync runs asynchronously; use status to check it. Repeating
create is safe, including when enabling succeeded but placement failed.
locations and create also support --json and --jq.
GitLab repositories cannot be mirrored until GitLab mirroring is enabled
for your organization. --source gitlab is available for deployments that
support it, including repositories in nested groups. If a GitLab repository
returns “not found,” check its connection to Avrea, your access, and whether
GitLab mirroring is enabled.
Watch a run live
avr run watch # auto-selects the latest active run for the current repo
avr run watch <run-id> # specific run
avr run watch <run-id> --exit-status # propagate the run's success/failure into the shell exit codeTriage a failure without leaving the terminal
avr run view <run-id> --log-failed # only the steps that failed, grouped by job
avr run logs <run-id> # full log dump, paginated
avr job logs <job-id> --follow # tail one job in real time
avr run diagnose <run-id> # timings, baseline, metrics and failed logsrun diagnose currently supports external CI runs; native Avrea CI runs
are not supported by that command.
Read recorded tests from a run or job
avr tests <run-id> --job unit # select one job by name
avr tests <github-run-id> # a single-job run needs no selector
avr tests <job-id> # names, outcomes, timings and failures
avr tests <job-id> --status failed --status errored
avr tests <run-id> --job unit --summary # counts and reporting state only
avr tests <job-id> --test test_login
avr tests <job-id> --suite Authentication --class TestLogin
avr tests <job-id> --json '*' # reporting state and pagination
avr tests <job-id> --limit 500 # maximum matching occurrences to return
avr tests <job-id> --cursor '<cursor>' # resume with the same filtersAccepts Avrea run IDs (run- or awr-), GitHub numeric run IDs, GitHub
Actions run/job URLs, Avrea console run URLs, and Avrea job IDs (job- or
awj-). avr tests list <run-or-job> is equivalent. A run selects one job,
not all jobs together. --job NAME matches a case-insensitive substring and
must identify one job; ambiguous names show the available jobs and IDs.
A run containing one job selects it automatically. The job's repository is
resolved automatically, or use --repo owner/name.
A GitHub job URL pins that job; --job must also match its name.
The listing reads the job's latest confirmed execution, without substituting
an older report. GitHub run URLs with /attempts/N select that run attempt;
there is no separate test-execution selector. Test names match exactly and
case-sensitively; test filters combine with AND. Outcomes are passed,
failed, skipped and errored. Repeat --status to match any selected
outcome; repeated values are deduplicated. Repeated matches stay separate, with their
recorded failure messages shown directly. --json FIELDS and --jq also work.
--summary reads report counts and reporting state without downloading
individual tests. Counts cover all recorded occurrences before filtering,
including repeats. Older, missing or expired reports may have unknown counts;
unknown counts never mean zero. --summary accepts run and job selection but
cannot be combined with test filters, --cursor or an explicit --limit.
Each invocation returns at most 1,000 occurrences and reads at most 20 result
pages. Filtering can produce empty pages with a continuation. If the search
stops before the report ends, the command says so; resume with the same job,
filters and --cursor. The retained count covers all tests, before filtering.
Missing or expired reports are distinct from zero matches or a retained
report containing zero tests. Complete describes collected reports, not
whether every expected test ran.
Indexing, unavailable and limited listings retain known counts and explain
why individual results could not be listed.
These commands require an API deployment supporting the corresponding reads, including summaries and combined status filters when those options are used. Filtering fails explicitly if the server does not acknowledge the selectors. File filters and test splitting are not supported. The commands do not rerun tests or change collection.
Trigger a workflow_dispatch
avr workflow run ci.yml # default branch
avr workflow run ci.yml --ref feat/x -f env=staging # with inputs
avr workflow run "Build and Deploy" --watch --exit-status # dispatch + watch + script-friendly exit
echo '{"env":"prod"}' | avr workflow run deploy.yml --json # inputs from stdinWORKFLOW accepts an Avrea ID (wfl-...), the GitHub numeric ID, a filename (ci.yml, ci), or the display name.
SSH into a running job's VM
avr job ssh <job-id>
avr job ssh <job-id> --print-command # just print the ssh stringLive VM metrics while a job runs
avr job metrics <job-id> --watch # CPU/memory/IO gauges, streamed live
avr job metrics <job-id> # static post-mortem after the job endedLong-running dev VMs
Durable, org-scoped VMs reachable over SSH (plus RDP/VNC for a desktop), separate from job VMs. Create one with your key, then set it up in a single command:
avr vm create --name dev --os linux --size 2-vcpu \
--ssh-key @~/.ssh/id_ed25519.pub --wait # boot, wait for SSH, print connect
avr vm create --name ci --os linux --size 8-vcpu \
--repo org/project --disable-cache gha,packages # attach a repo, narrow which caches it uses
avr vm bootstrap <vm-id> --setup-github --install claude,codex \
--repo https://github.com/org/project --env AWS_REGION=eu-north-1
avr vm ssh <vm-id> # SSH session, host key pinned when published (or: -- <cmd>)
avr vm ssh <vm-id> --login -- claude -p 'summarize the repo' # one-off command in a login shell (sees forwarded env)
avr vm ssh <vm-id> --session dev # persistent tmux session, survives a dropped connection
avr vm ssh-config <vm-id> --append # add `ssh <alias>` (scp/rsync, VS Code Remote-SSH) to ~/.ssh/config
avr vm list ; avr vm pause <vm-id> # lifecycle
avr vm resume <vm-id> --wait
avr vm fork <paused-vm-id> --name experiment --wait
avr vm capabilities
avr vm create --os linux --arch arm64 --size 2-vcpu --https-port 3000 --https-port 8080
avr vm metrics <vm-id> --watchbootstrap runs each step over SSH and streams it live, feeding secrets (GitHub token, env values, agent credentials) on stdin rather than argv. --forward-agent-creds carries your local ANTHROPIC_API_KEY / OPENAI_API_KEY, or a Claude subscription token — if none is set it offers to run claude setup-token and forwards the pasted CLAUDE_CODE_OAUTH_TOKEN. Bootstrap changes survive pause and resume. avr vm ssh pins the VM's host key when its endpoint publishes one; if it doesn't, avr warns and falls back to trust-on-first-use — pass --session <name> to attach to (or create) a persistent tmux session that survives a dropped connection. A one-off avr vm ssh -- <cmd> runs in a non-login shell that sources no startup files, so pass --login when the command needs bootstrap-forwarded env (e.g. claude's subscription token). avr vm ssh-config emits a host-key-pinned SSH config block so plain ssh, scp/rsync, and VS Code / Cursor Remote-SSH reach the VM without wrapping each tool — --append writes it into ~/.ssh/config for you (idempotent: re-run after a resume to refresh the endpoint in place). For a desktop, avr vm rdp / avr vm vnc tunnel over the same SSH endpoint, and avr vm port-forward is the generic primitive (repeat --port to forward several ports over one connection). A VM created with --repo inherits that repository's build/CI caches; --disable-cache <name> narrows them per VM (it can turn an inherited cache off, never on).
VM references accept IDs or display names. Names are generated when omitted. TTL expiry pauses the VM, or deletes it when pausing is unavailable. Agent sandboxes boot once and cannot be paused or resumed. HTTPS URLs are public to anyone who has them; the first configured port is the default. Port updates apply live on a running VM, otherwise at the next start or resume; avr vm rotate-https-label replaces leaked URLs. Metrics watch uses a WebSocket stream for both VM and job metrics; explicit --start/--end windows require single-shot mode.
Cancel or rerun a run
avr run cancel <run-id>
avr run rerun <run-id>
avr run rerun <run-id> --failed # only failed jobsWorkflow stats and the slowest steps
avr workflow list # aggregate stats per workflow over the last 30d
avr workflow view <wfl-id> # per-job p95/median/failure breakdown + recent runs
avr status # current repo: recent runs, performance and cache healthCache
avr cache list --repo <repo> # entries
avr cache usage --repo <repo> # size vs quota
avr cache delete --key <key> --type <type> --repo <repo>Use --json for structured output on list/view commands. Check each command's
--help for available fields; commands such as status and run diagnose
accept a plain --json switch instead of a field list.
Discover available fields
avr run list --json '?' # prints the field schemaSelect specific fields
avr run list --json status,conclusion,head_branch
avr run list --json '*' # all fieldsPipe through jq
avr run list --json '*' -q '.[] | select(.conclusion == "failure") | .run_id'
avr workflow list --json name,runs -q '.[] | "\(.runs)\t\(.name)"'-q/--jq is built in (no need to pipe to jq yourself), but the schema-projected output is also jq-friendly.
The Go CLI uses embedded gojq, like GitHub CLI: object keys are sorted. For ordered columns use explicit fields, for example [.status,.conclusion,.run_id]. See installation notes.
Detect "auth required" in scripts
avr run list >/dev/null
result=$?
case "$result" in
0) ;;
4) echo "logged out, re-auth needed"; exit 4 ;;
*) echo "command failed (exit $result)" >&2; exit "$result" ;;
esacExit code 4 is reserved for "auth required". 1 is general failure; 2 is a usage error. 130 means Ctrl-C
ended the command, including a watch, a log follow or a tunnel that is stopped that way.
Scoped tokens for scripts and agents
avr token create --name ci-read --org <org-id> --repo acme/api --ttl 8h # prints the credential once
avr token create --name agent --org <org-id> --vm <vm-id> --allow-vm-create --vm-create-limit 3
avr token list
avr token view <token-id>
avr token revoke <token-id>A scoped token is a short-lived credential (60 seconds to 7 days, 8 hours by default) bound to one organization. Repository grants are read-only and VM grants are admin: it reads only the repositories it names, has admin access to only the VMs it names, and cannot create further tokens. create prints the export AVR_TOKEN=... and export AVR_ORG=... lines for whatever will use the token. Scoped tokens require the org-... ID in AVR_ORG or --org; they ignore the login's stored organization and cannot resolve a slug. avr auth status reports this configuration without checking whether the token is still live. A 403 or 404 comes with a reminder that the token reaches only what it names.
avr repo clone acme/api uses the owner/repository name directly.
With a scoped token, a repository name (--repo acme/api, AVR_REPO or the checkout's remote) is matched against the repositories the token reaches; a rep-... ID works as well. For runs, use the run ID rather than an Avrea console URL, whose organization slug cannot be resolved with a scoped token. Token IDs for view and revoke are key- followed by 32 lowercase hexadecimal characters.
Creation returns the credential only once. If --jq fails or removes it, the command falls back to the requested JSON without filtering and exits nonzero. Save the credential from that JSON. Output failures also report a revoke command on stderr without exposing the credential there. If the creation request is interrupted, its response is lost, or the answer is a server error (5xx), a token may already exist: check avr token list before retrying. Only a 503 that carries the API's own reason means that no token was created.
If avr token create returns a 404, check the API's reason, the organization and the API host. If scoped-token access is unavailable, contact support@avrea.com to request it. VM grants and --allow-vm-create also require customer VMs to be enabled for the organization. list, view and revoke remain available when token creation is disabled.
Pipe-aware output
When stdout isn't a TTY, list commands switch to tab-separated rows (no color, no truncation, ISO timestamps), so avr run list | awk works without flags. Control characters, Unicode line separators and bidirectional controls inside cells are escaped (\t, \x1b, \u2028), keeping each item on one row with stable columns. The escaping is not reversible: a literal backslash is left as it is, so a cell that reads a\tb may hold either a tab or a backslash and a t. Use --json when the exact value matters; JSON retains the original values. avr run watch | jq -c . automatically switches to NDJSON event mode.
| Variable | Purpose |
|---|---|
AVR_HOST |
Avrea API URL. Defaults to the active host in hosts.json, then https://api.avrea.com. |
AVR_TOKEN |
API key or scoped token. Overrides whatever's stored for the active host. |
AVR_ORG |
Default organization ID. Overrides the stored default. A scoped token needs it, or --org, except for repo clone. |
AVR_REPO |
Default repository (org/name or rep-xxx). Overrides git auto-detect. |
AVR_BROWSER |
Browser to launch for --web and OAuth login. Falls back to BROWSER, then system default. |
AVR_PAGER |
Pager for long output. Overrides PAGER. Set to empty string to disable paging. |
AVR_LINKS |
Set to 0 to disable OSC 8 hyperlinks. Same as --no-links. |
AVR_DEBUG |
Set to api for request diagnostics or timing for timing measurements; 1/true enables request diagnostics. |
AVR_NO_UPDATE_NOTIFIER |
Set to 1 to disable update checks and notices. |
AVR_PROMPT_DISABLED |
Refuse interactive prompts (scripts fail fast instead of hanging on stdin). |
AVR_CONFIG_DIR |
Override the config directory. Defaults to $XDG_CONFIG_HOME/avrea or ~/.config/avrea. |
AVR_MACOS_NATIVE_PATHS |
Set to 1 on macOS to use ~/Library/... instead of the default ~/.config/avrea. |
NO_COLOR |
Disable colored output (any non-empty value). Same as --no-color. |
avr config # status: host, auth, org, repo with sources
avr config list # same as bare `avr config`
avr config set org <org-id> # store a default organization
avr config get org
avr config unset orgPersistent state lives in $XDG_CONFIG_HOME/avrea/hosts.json (host-keyed credentials and per-host defaults).
avr auth switch # interactive picker across stored hosts
AVR_HOST=https://beta.api.avrea.com avr run list # one-shot overrideOpen anything on the console
avr run view <run-id> --web
avr workflow view <wfl-id> --web
avr cache list --repo <repo> --webClick-to-open in your terminal
IDs in tables are wrapped in OSC 8 hyperlinks. Clicking one opens the matching console page in your browser (supported by iTerm2, Kitty, WezTerm, Ghostty, GNOME Terminal, Konsole, Windows Terminal, and most modern terminals). Disable with --no-links or AVR_LINKS=0 if your terminal renders them as visible garbage.
Tab completion
# bash
eval "$(_AVR_COMPLETE=bash_source avr)"
# zsh (initialize completion first if your shell has not already done so)
autoload -Uz compinit && compinit
eval "$(_AVR_COMPLETE=zsh_source avr)"
# fish
_AVR_COMPLETE=fish_source avr | sourceVerbose mode
avr -v run list # prints HTTP requests, useful for debuggingFilter the help surface
avr --help # top-level groups
avr <group> --help # subcommands
avr <group> <command> --help # full flag list with examples- Send feedback and check delivery, including safe retries.
- Full command reference:
docs/REFERENCE.md. The native Homebrew formula also installsman avr; native archives include man pages for manual installation. - Online docs: docs.avrea.com/cli
- Print the same reference inline:
avr --helpandavr <command> --help
- Bug reports and feature requests: github.com/avrea-com/cli/issues
If you believe you have found a security issue in avr, please email
security@avrea.com. Do not open a public issue. See SECURITY.md
for our coordinated-disclosure policy, response targets, and safe-harbour terms.
Licensed under the Apache License, Version 2.0. Copyright 2026 Avrea.