avr-cli 0.4.1__tar.gz → 0.6.0__tar.gz

{avr_cli-0.4.1 → avr_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avr-cli
-Version: 0.4.1
+Version: 0.6.0
 Summary: Avrea command-line client
 Author-email: Avrea <support@avrea.com>
 License-Expression: Apache-2.0
@@ -11,22 +11,26 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: anyio>=4.14.2
+Requires-Dist: certifi>=2026.10.19
 Requires-Dist: click>=8.3.1
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: platformdirs>=4.0
 Requires-Dist: prettytable>=3.17.0
+Requires-Dist: segno>=1.6.6
 Requires-Dist: pydantic>=2.12.4
 Requires-Dist: typing-extensions>=4.15.0
 Requires-Dist: idna>=3.15
+Requires-Dist: websockets>=15
 Provides-Extra: dev
 Requires-Dist: pytest>=9.0.3; extra == "dev"
 Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
 Requires-Dist: pytest-timeout>=2.4.0; extra == "dev"
-Requires-Dist: ruff==0.15.13; extra == "dev"
+Requires-Dist: ruff==0.17.3; extra == "dev"
 Requires-Dist: ty==0.0.15; extra == "dev"
 Dynamic: license-file
 
@@ -88,6 +92,19 @@ Browser-based login (recommended):
 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
@@ -117,6 +134,62 @@ Auto-detection means most commands "just work" without `--repo`. Outside a git t
 
 ## 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
@@ -133,6 +206,48 @@ 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
@@ -154,7 +269,7 @@ 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, refreshed every few seconds
+avr job metrics <job-id> --watch       # CPU/memory/IO gauges, streamed live
 avr job metrics <job-id>               # static post-mortem after the job ended
 ```
 
@@ -164,8 +279,8 @@ Durable, org-scoped VMs reachable over SSH (plus RDP/VNC for a desktop), separat
 
 ```sh
 avr vm create --name dev --os linux --size 2-vcpu \
-  --ssh-key @~/.ssh/id_ed25519.pub --ephemeral --wait      # boot, wait for SSH, print connect
-avr vm create --name ci --os linux --size 8-vcpu --ephemeral \
+  --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
@@ -173,10 +288,17 @@ avr vm ssh <vm-id>                                          # SSH session, host
 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 stop <vm-id>                           # lifecycle
+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`. Disks are ephemeral, so re-run it after every `avr vm start`. `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 restart 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).
+`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**
 
@@ -239,11 +361,32 @@ case $? in
 esac
 ```
 
-Exit code `4` is reserved for "auth required". `1` is general failure; `2` is a usage error.
+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. `avr run watch | jq -c .` automatically switches to NDJSON event mode.
+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
 
@@ -252,8 +395,8 @@ When stdout isn't a TTY, list commands switch to tab-separated rows (no color, n
 | Variable         | Purpose                                                                                          |
 | ---------------- | ------------------------------------------------------------------------------------------------ |
 | `AVR_HOST`       | Avrea API URL. Defaults to the active host in `hosts.json`, then `https://api.avrea.com`.        |
-| `AVR_TOKEN`      | API key. Overrides whatever's stored for the active host.                                         |
-| `AVR_ORG`        | Default organization ID. Overrides the stored default.                                           |
+| `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.                  |