avr-cli 0.7.0__py3-none-win_amd64.whl

avr_cli-0.7.0.data/data/share/avr/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Avrea
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

avr_cli-0.7.0.data/data/share/avr/README.md

@@ -0,0 +1,461 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/avrea-com/cli/main/.github/banner.png" alt="Avrea CLI" width="640" />
+</p>
+
+# Avrea CLI
+
+Official command-line client for [Avrea](https://avrea.com/). `avr` brings runs, jobs, logs, and workflow control into your terminal.
+
+## Install
+
+AVR 0.7.0 uses a native Go executable, keeping the `avr` command and existing
+package-manager upgrade paths. See [installation and updates](https://github.com/avrea-com/cli/blob/main/docs/INSTALL.md)
+for supported platforms, installation methods, and upgrade details.
+
+### Homebrew
+
+```sh
+brew install avrea-com/tap/avr
+```
+
+### PyPI
+
+```sh
+uv tool install avr-cli
+```
+
+These commands install the latest published version. Native wheels (0.7.0+)
+require Python 3.9+ for installation; the installed `avr` executable runs
+without Python. The older 0.6.0 package requires Python 3.14+ at runtime.
+You can also install with pip:
+
+```sh
+pip install avr-cli
+```
+
+### From source
+
+```sh
+git clone git@github.com:avrea-com/cli.git
+cd cli
+make go-build
+./build/go/avr --version
+```
+
+Source builds require Go 1.27.3+ and uv (for packaging tools). Run
+`make test` for native and tooling tests, and `make lint` for both languages.
+
+### Verifying a release
+
+Release artefacts (the native archives and PyPI wheels) carry keyless
+[SLSA build provenance](https://slsa.dev/) signed via Sigstore. Verify a
+downloaded artefact against this repository with the GitHub CLI:
+
+```sh
+gh attestation verify avr_0.7.0_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):
+
+```sh
+avr auth login
+```
+
+On a remote machine, VM, or terminal without a browser:
+
+```sh
+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:
+
+```sh
+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):
+
+```sh
+avr auth logout
+```
+
+For non-interactive environments (CI, scripts), set a token via env var instead. See [Configuration](#configuration).
+
+## Your first command
+
+Inside any git checkout of an Avrea-connected repository:
+
+```sh
+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**
+
+```sh
+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:
+
+```sh
+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**
+
+```sh
+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**
+
+```sh
+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**
+
+```sh
+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**
+
+```sh
+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**
+
+```sh
+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**
+
+```sh
+avr job ssh <job-id>
+avr job ssh <job-id> --print-command   # just print the ssh string
+```
+
+**Live VM metrics while a job runs**
+
+```sh
+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:
+
+```sh
+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**
+
+```sh
+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**
+
+```sh
+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**
+
+```sh
+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**
+
+```sh
+avr run list --json '?'                # prints the field schema
+```
+
+**Select specific fields**
+
+```sh
+avr run list --json status,conclusion,head_branch
+avr run list --json '*'                # all fields
+```
+
+**Pipe through `jq`**
+
+```sh
+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](docs/INSTALL.md#json-and-jq).
+
+**Detect "auth required" in scripts**
+
+```sh
+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**
+
+```sh
+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
+
+| 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`      | Comma-separated debug categories. Set to `1`/`true` for general debug logging.                    |
+| `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`.                                |
+
+### Config commands
+
+```sh
+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
+
+```sh
+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**
+
+```sh
+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**
+
+```sh
+# bash
+eval "$(_AVR_COMPLETE=bash_source avr)"
+# zsh
+eval "$(_AVR_COMPLETE=zsh_source avr)"
+# fish
+_AVR_COMPLETE=fish_source avr | source
+```
+
+**Verbose mode**
+
+```sh
+avr -v run list                   # prints HTTP requests, useful for debugging
+```
+
+**Filter the help surface**
+
+```sh
+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`](./docs/REFERENCE.md) (also available as `man avr`)
+- Online docs: [docs.avrea.com/cli](https://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](https://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](SECURITY.md)
+for our coordinated-disclosure policy, response targets, and safe-harbour terms.
+
+## License
+
+Licensed under the [Apache License, Version 2.0](./LICENSE). Copyright 2026 Avrea.