Avrea CLI

Official command-line client for Avrea. avr brings runs, jobs, logs, and workflow control into your terminal.

Install

Homebrew

brew install avrea-com/tap/avr

PyPI

uv tool install avr-cli

uv tool install puts avr on your PATH in an isolated environment and fetches Python 3.14 automatically if you don't have it. Or, with an existing Python 3.14:

pip install avr-cli

From source

git clone https://github.com/avrea-com/cli && cd cli && uv sync
uv run avr --version

Verifying a release

Release artefacts (the binary tarballs and the PyPI wheel/sdist) carry keyless SLSA build provenance signed via Sigstore. Verify a downloaded artefact against this repository with the GitHub CLI:

gh attestation verify avr_0.1.5_linux_amd64.tar.gz --repo avrea-com/cli

A successful check confirms the artefact was built by this repository's release workflow and has not been tampered with.

Authenticate

Browser-based login (recommended):

avr auth login

On a remote machine, VM, or terminal without a browser:

avr auth device-login

Open 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 sources

Log out (revokes the active API key on the server):

avr auth logout

For non-interactive environments (CI, scripts), set a token via env var instead. See Configuration.

Your first command

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 output

Auto-detection means most commands "just work" without --repo. Outside a git tree (or to override), pass --repo org/name or --repo rep-xxx.

Common workflows

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.io

Avrea 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 HEAD

Tokens 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 code

Triage 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

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
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 filters

Accepts Avrea run IDs (run- or awr-), GitHub numeric run IDs, GitHub Actions run 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.

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. Repeated matches stay separate, with their recorded failure messages shown directly. --json FIELDS and --jq also work.

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.

These commands require an API deployment supporting the corresponding reads. 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 stdin

WORKFLOW 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 string

Live 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 ended

Long-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> --watch

bootstrap 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 jobs

Workflow 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                             # org-wide health: recent runs, slowest workflows, cache usage

Cache

avr cache list --repo <repo>           # entries
avr cache usage --repo <repo>          # size vs quota
avr cache delete --key <key> --type <type> --repo <repo>

Scripting & automation

Every list/view command supports --json for structured output.

Discover available fields

avr run list --json '?'                # prints the field schema

Select specific fields

avr run list --json status,conclusion,head_branch
avr run list --json '*'                # all fields

Pipe 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.

Detect "auth required" in scripts

avr run list >/dev/null
case $? in
  0) ;;
  4) echo "logged out, re-auth needed"; exit 4 ;;
  *) echo "transient failure" ;;
esac

Exit 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.

Configuration

Environment variables

Config commands

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 org

Persistent state lives in $XDG_CONFIG_HOME/avrea/hosts.json (host-keyed credentials and per-host defaults).

Switching hosts

avr auth switch                   # interactive picker across stored hosts
AVR_HOST=https://beta.api.avrea.com avr run list   # one-shot override

Tips

Open anything on the console

avr run view <run-id> --web
avr workflow view <wfl-id> --web
avr cache list --repo <repo> --web

Click-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
eval "$(_AVR_COMPLETE=zsh_source avr)"
# fish
_AVR_COMPLETE=fish_source avr | source

Verbose mode

avr -v run list                   # prints HTTP requests, useful for debugging

Filter the help surface

avr --help                        # top-level groups
avr <group> --help                # subcommands
avr <group> <command> --help      # full flag list with examples

Documentation

• Full command reference: docs/REFERENCE.md (also available as man avr)
• Online docs: docs.avrea.com/cli
• Print the same reference inline: avr --help and avr <command> --help

Contributing and reporting issues

• Bug reports and feature requests: github.com/avrea-com/cli/issues

Reporting a vulnerability

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.

License

Licensed under the Apache License, Version 2.0. Copyright 2026 Avrea.