albus-cli 0.1.0__tar.gz → 0.2.0__tar.gz

albus_cli-0.2.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,61 @@
+name: Bug report
+description: Report incorrect or unexpected behavior in the albus command
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The CLI is maintained upstream, and this repository is a mirror of each
+        release. Fixes land upstream and arrive in the next published version,
+        which closes the issue.
+
+        **Never paste access tokens, API keys, secret values, or customer data
+        into this issue.** Redact them from commands, logs, and tracebacks.
+        Report suspected vulnerabilities privately through
+        [SECURITY.md](https://github.com/albusgroup/albus-cli/blob/master/SECURITY.md)
+        instead of opening an issue.
+
+  - type: input
+    id: cli-version
+    attributes:
+      label: albus-cli version
+      description: Output of `pip show albus-cli` or `uv tool list`.
+      placeholder: "0.2.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      description: Output of `python --version`.
+      placeholder: "3.12.4"
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Command and output
+      description: >
+        The command you ran and what it printed, with credentials and customer
+        data removed.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: >
+        What happened instead, including the exit status, the HTTP status, and
+        redacted output when relevant.
+    validations:
+      required: true

albus_cli-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/albusgroup/albus-cli/blob/master/SECURITY.md
+    about: Report privately. Do not open a public issue for a vulnerability.
+  - name: How this repository is maintained
+    url: https://github.com/albusgroup/albus-cli/blob/master/CONTRIBUTING.md
+    about: This is a release mirror. It accepts issues, not pull requests.

albus_cli-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,10 @@
+**This repository does not accept pull requests, and this one will be closed
+automatically.**
+
+It is a mirror of the Albus CLI: every release overwrites the whole tree, so a
+merge here is deleted by the next published version.
+
+Open an [issue](https://github.com/albusgroup/albus-cli/issues/new/choose)
+instead and include your patch in the body. Maintainers apply the fix upstream,
+and it ships in the next release, which closes the issue. See
+[CONTRIBUTING.md](https://github.com/albusgroup/albus-cli/blob/master/CONTRIBUTING.md).

albus_cli-0.2.0/.github/workflows/close-pull-requests.yml

@@ -0,0 +1,51 @@
+name: Close pull requests
+
+# This repository is a mirror: every release overwrites its tree, so a merged
+# pull request is deleted by the next release. GitHub cannot disable pull
+# requests, so opened ones are closed here with a pointer to issues.
+#
+# pull_request_target runs this file from the default branch with a read/write
+# token, so it also works for pull requests opened from forks.
+on:
+  pull_request_target:
+    types: [opened, reopened]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  close:
+    runs-on: ubuntu-latest
+
+    steps:
+      - env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          PULL_REQUEST: ${{ github.event.number }}
+          AUTHOR: ${{ github.event.pull_request.user.login }}
+        run: |
+          cat > comment.md <<EOF
+          Thanks for taking the time to write this, @${AUTHOR} — but this
+          repository is a read-only mirror of the Albus CLI, and every release
+          overwrites its entire tree. A pull request merged here would be
+          deleted by the next published version, so this one is being closed
+          unmerged.
+
+          Please open an issue instead:
+          https://github.com/${GH_REPO}/issues/new/choose
+
+          Describe the behavior you expected, and include the diff or patch
+          from this pull request in the issue body. Maintainers apply the fix
+          in the private upstream repository, and it reaches you in the next
+          release, which closes the issue.
+
+          Report suspected vulnerabilities privately through
+          [SECURITY.md](https://github.com/${GH_REPO}/blob/master/SECURITY.md),
+          not as a public issue.
+
+          See [CONTRIBUTING.md](https://github.com/${GH_REPO}/blob/master/CONTRIBUTING.md)
+          for how this repository is maintained.
+          EOF
+
+          gh pr comment "$PULL_REQUEST" --body-file comment.md
+          gh pr close "$PULL_REQUEST"

{albus_cli-0.1.0 → albus_cli-0.2.0}/.gitignore

@@ -6,4 +6,3 @@ __pycache__/
 .ruff_cache/
 dist/
 build/
-.tmp/

albus_cli-0.2.0/AGENTS.md

@@ -0,0 +1,85 @@
+# albus-cli
+
+Source of truth for the public `albus-cli` Python package: the `albus`
+command-line client for the Albus REST API, built on `albus-sdk`. Releases are
+published to PyPI and copied out to the public `albusgroup/albus-cli`
+repository, which is a mirror. See
+[`.agents/plans/sdk-publishing-from-monorepo.md`](../../.agents/plans/sdk-publishing-from-monorepo.md)
+and the repository-wide
+[engineering style guide](../../.agents/style-guide.md).
+
+## Commands
+
+Run everything from `clients/albus-cli/`. `uv` owns the virtualenv and
+`uv.lock`.
+
+| Command | Purpose |
+|---|---|
+| `./setup.sh` | Install `uv`, Python 3.11, and the development environment |
+| `make install` | `uv sync` |
+| `make lint` | `ruff check` + `ruff format --check` |
+| `make typecheck` | `mypy --strict` |
+| `make test` | `pytest` |
+| `make check` | all of the above |
+| `./tools/check` | `make check`, and what a release runs |
+| `./tools/publish --dry-run <version>` | Validate a release without uploading |
+| `./tools/publish [--testpypi] <version>` | Upload, after explicit authorization |
+| `./tools/mirror-release [--dry-run] <version> <checkout>` | Copy the released tree to the public mirror |
+
+See [`RELEASING.md`](RELEASING.md). Publishing is never implied by a merge: a
+version reaches PyPI only when it was explicitly authorized, and published
+versions are immutable.
+
+## Conventions
+
+- The CLI owns argument parsing, output, and error reporting only. Request
+  building, retries, and response types belong to `albus-sdk`; never hand-roll
+  HTTP calls or redefine SDK models.
+- Every command maps to exactly one SDK operation and prints its response as
+  JSON via `output.emit`. Do not add per-command formatting or extra
+  round trips.
+- `login` and `logout` are the one exception: they sign in to Auth0 rather
+  than call Albus, so they drive `oauth.py` and the credential store, and
+  print prose. `login` also reads back `/whoami` to name the account it
+  signed in as. Any further exception needs the same kind of reason.
+- `output.py` owns every colour the CLI emits, prose included: a command
+  composes its report from `progress`, `done`, `field`, `link`, and `note`
+  rather than calling `typer.secho` itself. Styling must survive being
+  piped, which means letting Typer drop the escapes and never writing them
+  by hand.
+- `client.py` is the single owner of credential and transport configuration.
+  It resolves `ALBUS_API_KEY` first, then the stored browser session for the
+  base URL — renewing it when it has expired — and otherwise fails with a
+  message naming both ways to get a credential.
+- A command wrapping an operation whose `security` in `api/openapi.yaml`
+  lists `bearerAuth` only (`whoami`, `tokens`, `invites`) builds its client
+  with `signed_in_client`, which uses the browser session and never an API
+  key: the key would be a 401 the caller cannot act on.
+- Never print or log a token. Every sentence about a credential — not signed
+  in, expired, rejected, shadowed by an API key — is written in `client.py`,
+  which is the only place that knows which credential was sent. An
+  instruction for the credential the command did not use is worse than none.
+- Renewing a stored session goes through `credentials.renew`, which holds the
+  store's lock across the Auth0 call. Two processes spending one refresh
+  token is a rotation reuse, and Auth0 revokes the family.
+- Nothing from the credential store or `oauth.py` reaches the terminal as a
+  traceback; `main.py` turns it into an instruction naming the file.
+- Tests drive commands through `typer.testing.CliRunner` with a fake SDK; they
+  never reach the network.
+- Keep lines at 81 characters or fewer (`ruff` enforces it).
+- The `albus-sdk` dependency is pinned to one version. The published CLI has
+  to name an SDK version that exists on PyPI, so the pin is bumped
+  deliberately in the pull request that needs the newer SDK — never floated to
+  whatever is latest at install time.
+- The public repository accepts issues, not pull requests. A user-reported bug
+  is fixed here and reaches them in the next release, which closes the issue
+  via a `Mirror-Issue: albusgroup/albus-cli#<n>` trailer on the fix's commit.
+- `.github/` is the mirror's, not this repository's: GitHub only runs workflows
+  and reads templates from a repository root, so these files are inert here and
+  active once the release copies the tree out. Anything the mirror needs
+  belongs here, since the release overwrites its entire tree. This repository's
+  own CI for the CLI is `.github/workflows/cli-test.yml` at the root.
+- `install.sh` and `install.ps1` are what the public install instructions pipe
+  into a shell. They install the published package from PyPI and must keep
+  working against the mirror's `master`, which is where the documented URLs
+  point.

albus_cli-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing to albus-cli
+
+Thanks for helping improve the Albus CLI.
+
+## Report a problem
+
+Open a [GitHub issue](https://github.com/albusgroup/albus-cli/issues) with:
+
+- The installed `albus-cli` and Python versions.
+- The command you ran and the exact output.
+- The expected and actual behavior.
+
+Do not include access tokens, organization keys, secret values, or other
+sensitive data. `albus` never prints a credential; if you have pasted one into
+a log, redact it and rotate the credential.
+
+Report suspected vulnerabilities privately by following
+[SECURITY.md](SECURITY.md), not by opening a public issue.
+
+## This repository is a mirror
+
+The CLI is developed in the private Albus repository, alongside the
+`api/openapi.yaml` contract and the SDK it is built on, and each release is
+copied here. This repository does not accept pull requests: a change merged
+here is removed by the next release, so one opened here is commented on and
+closed automatically.
+
+Issues are the right channel, and they are read. Maintainers fix the problem
+upstream, and the fix arrives in the next published version, which closes the
+issue.
+
+See [RELEASING.md](RELEASING.md) for how a version is produced and published.

{albus_cli-0.1.0 → albus_cli-0.2.0}/Makefile

@@ -1,5 +1,7 @@
 .PHONY: install lint fmt typecheck test check
 
+# uv owns the virtualenv. The albus-sdk version is pinned in pyproject.toml,
+# so a sync installs what a release would publish against.
 install:
 	uv sync
 

albus_cli-0.2.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.5
+Name: albus-cli
+Version: 0.2.0
+Summary: Command-line client for the Albus REST API
+Project-URL: Homepage, https://github.com/albusgroup/albus-cli
+Project-URL: Repository, https://github.com/albusgroup/albus-cli
+Project-URL: Issues, https://github.com/albusgroup/albus-cli/issues
+Author: Albus
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: albus-sdk==0.6.0
+Requires-Dist: typer<0.28,>=0.26.8
+Description-Content-Type: text/markdown
+
+# albus CLI
+
+Command-line client for the Albus REST API, built on the public
+[`albus-sdk`](https://pypi.org/project/albus-sdk/) Python SDK. It is a thin
+shell over the SDK: every command that calls Albus maps to one API operation
+and prints the JSON response, so output pipes into `jq`.
+
+## Install
+
+macOS / Linux:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/albusgroup/albus-cli/master/install.sh | sh
+```
+
+Windows (PowerShell):
+
+```powershell
+irm https://raw.githubusercontent.com/albusgroup/albus-cli/master/install.ps1 | iex
+```
+
+Pin a version:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/albusgroup/albus-cli/master/install.sh | ALBUS_CLI_VERSION=0.2.0 sh
+```
+
+The installer uses, in order: `uv tool install`, `pip install --user`, or
+`pip` inside a conda environment. It does not download OS-specific binaries.
+To install directly instead:
+
+```bash
+uv tool install albus-cli
+# or
+pip install --user albus-cli
+```
+
+## Authentication
+
+Sign in with a browser, which stores a session per base URL and renews it as
+it expires:
+
+```bash
+albus login
+albus whoami
+albus logout
+```
+
+`albus health` is the one command that needs no credential, matching its empty
+`security` in `api/openapi.yaml`: run it first to tell an unreachable API from
+an unauthenticated one. `albus status` reports which credential is in effect
+and whether Albus accepts it, as JSON, exiting 0 either way — it is the one
+command to run to find out where you stand. `albus login --no-browser` prints
+the authorization URL instead of opening it, for a coding agent signing in the
+user in front of it.
+
+Or export an organization API key, which wins over a stored session so CI and
+agent harnesses need not touch disk:
+
+```bash
+export ALBUS_API_KEY=...     # organization API key
+export ALBUS_BASE_URL=http://localhost:8080/api  # optional; defaults to prod
+```
+
+`--base-url` overrides `ALBUS_BASE_URL`, and `--timeout` bounds each request
+(a waiting `sessions run` long-polls and is exempt).
+
+`albus login` opens a browser on this machine and listens on
+`127.0.0.1:8484-8487`; on a headless host, forward those ports or export
+`ALBUS_API_KEY` instead. The
+session is written to `$ALBUS_CONFIG_DIR/credentials.json`, else
+`$XDG_CONFIG_HOME/albus/credentials.json`, else `~/.config/albus/`.
+
+Operations whose `security` in `api/openapi.yaml` lists `bearerAuth` only,
+such as `/whoami`, `/tokens`, and `/invites`, need the browser session.
+`albus whoami`, `albus tokens`, and `albus invites` use it even when
+`ALBUS_API_KEY` is exported, and say to run `albus login` when there is none.
+Sign in first, then `albus tokens create` to mint the key that
+`ALBUS_API_KEY` carries.
+
+## Commands
+
+```bash
+albus health
+albus --version
+albus login
+albus login --no-browser
+albus whoami
+albus logout
+albus status
+
+albus sessions run my-session -p "summarize the incident" \
+  --agent-name support-triage --model gemini-3.6-flash \
+  --provider gemini --credential albus.sh/secrets/gemini-key
+albus sessions run my-session -p "and the follow-up?" \
+  --agent-name support-triage --agent-file agent.json --no-wait
+albus sessions list
+albus sessions get my-session --limit 20
+albus sessions audit my-session --after "$cursor"
+albus sessions delete my-session
+
+albus secrets list
+albus secrets create gemini-key --value ...   # or pipe the value on stdin
+albus secrets get gemini-key
+albus secrets update gemini-key < value.txt
+albus secrets delete gemini-key
+
+albus agents list
+albus agents get support-triage
+albus agents revision support-triage "$revision"
+
+albus tokens list
+albus tokens create ci
+albus tokens get "$id"
+albus tokens delete "$id"
+
+albus invites create teammate@example.com
+```
+
+`tokens create` prints the only copy of the key value the API ever returns;
+`list` and `get` return metadata alone.
+
+`invites create` invites a person by email, and they get their own
+organization on first sign-in. `CreateInviteRequest`'s `role` and
+`organization_id` have no flags: one user is one organization for the beta.
+
+`sessions run` waits for the assistant response by default; pass `--no-wait`
+to return as soon as the invocation is accepted, or `--wait-timeout` to bound
+the wait server-side. Pass `--idempotency-key` to make a run retry-safe. The
+JSON output carries the effective `idempotency_key`, whether supplied by the
+caller or generated by the server — absent only if something between the CLI
+and Albus strips the response header on a run that supplied no key.
+
+`--agent-file` takes a JSON object shaped like the API's `AgentConfig` and
+covers what the flags do not (MCP servers, provider URL overrides):
+
+```json
+{
+  "model": { "name": "gemini-3.6-flash" },
+  "mcp_servers": [
+    { "name": "github", "url": "https://mcp.example.com/mcp" }
+  ]
+}
+```
+
+## Documentation
+
+| Reader | URL |
+|---|---|
+| A person | <https://docs.albus.sh> |
+| A coding agent | <https://docs.albus.sh/agents/docs.md> |
+
+The CLI prints both, so whoever is reading its output has the URL that is
+theirs.
+
+## Development
+
+The CLI is developed in the private Albus repository, next to the
+`api/openapi.yaml` contract and the SDK it is built on, and each release is
+copied to the public `albusgroup/albus-cli` repository. That repository accepts
+issues, not pull requests — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+```bash
+make check      # ruff, mypy --strict, pytest
+```

albus_cli-0.2.0/README.md

@@ -0,0 +1,165 @@
+# albus CLI
+
+Command-line client for the Albus REST API, built on the public
+[`albus-sdk`](https://pypi.org/project/albus-sdk/) Python SDK. It is a thin
+shell over the SDK: every command that calls Albus maps to one API operation
+and prints the JSON response, so output pipes into `jq`.
+
+## Install
+
+macOS / Linux:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/albusgroup/albus-cli/master/install.sh | sh
+```
+
+Windows (PowerShell):
+
+```powershell
+irm https://raw.githubusercontent.com/albusgroup/albus-cli/master/install.ps1 | iex
+```
+
+Pin a version:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/albusgroup/albus-cli/master/install.sh | ALBUS_CLI_VERSION=0.2.0 sh
+```
+
+The installer uses, in order: `uv tool install`, `pip install --user`, or
+`pip` inside a conda environment. It does not download OS-specific binaries.
+To install directly instead:
+
+```bash
+uv tool install albus-cli
+# or
+pip install --user albus-cli
+```
+
+## Authentication
+
+Sign in with a browser, which stores a session per base URL and renews it as
+it expires:
+
+```bash
+albus login
+albus whoami
+albus logout
+```
+
+`albus health` is the one command that needs no credential, matching its empty
+`security` in `api/openapi.yaml`: run it first to tell an unreachable API from
+an unauthenticated one. `albus status` reports which credential is in effect
+and whether Albus accepts it, as JSON, exiting 0 either way — it is the one
+command to run to find out where you stand. `albus login --no-browser` prints
+the authorization URL instead of opening it, for a coding agent signing in the
+user in front of it.
+
+Or export an organization API key, which wins over a stored session so CI and
+agent harnesses need not touch disk:
+
+```bash
+export ALBUS_API_KEY=...     # organization API key
+export ALBUS_BASE_URL=http://localhost:8080/api  # optional; defaults to prod
+```
+
+`--base-url` overrides `ALBUS_BASE_URL`, and `--timeout` bounds each request
+(a waiting `sessions run` long-polls and is exempt).
+
+`albus login` opens a browser on this machine and listens on
+`127.0.0.1:8484-8487`; on a headless host, forward those ports or export
+`ALBUS_API_KEY` instead. The
+session is written to `$ALBUS_CONFIG_DIR/credentials.json`, else
+`$XDG_CONFIG_HOME/albus/credentials.json`, else `~/.config/albus/`.
+
+Operations whose `security` in `api/openapi.yaml` lists `bearerAuth` only,
+such as `/whoami`, `/tokens`, and `/invites`, need the browser session.
+`albus whoami`, `albus tokens`, and `albus invites` use it even when
+`ALBUS_API_KEY` is exported, and say to run `albus login` when there is none.
+Sign in first, then `albus tokens create` to mint the key that
+`ALBUS_API_KEY` carries.
+
+## Commands
+
+```bash
+albus health
+albus --version
+albus login
+albus login --no-browser
+albus whoami
+albus logout
+albus status
+
+albus sessions run my-session -p "summarize the incident" \
+  --agent-name support-triage --model gemini-3.6-flash \
+  --provider gemini --credential albus.sh/secrets/gemini-key
+albus sessions run my-session -p "and the follow-up?" \
+  --agent-name support-triage --agent-file agent.json --no-wait
+albus sessions list
+albus sessions get my-session --limit 20
+albus sessions audit my-session --after "$cursor"
+albus sessions delete my-session
+
+albus secrets list
+albus secrets create gemini-key --value ...   # or pipe the value on stdin
+albus secrets get gemini-key
+albus secrets update gemini-key < value.txt
+albus secrets delete gemini-key
+
+albus agents list
+albus agents get support-triage
+albus agents revision support-triage "$revision"
+
+albus tokens list
+albus tokens create ci
+albus tokens get "$id"
+albus tokens delete "$id"
+
+albus invites create teammate@example.com
+```
+
+`tokens create` prints the only copy of the key value the API ever returns;
+`list` and `get` return metadata alone.
+
+`invites create` invites a person by email, and they get their own
+organization on first sign-in. `CreateInviteRequest`'s `role` and
+`organization_id` have no flags: one user is one organization for the beta.
+
+`sessions run` waits for the assistant response by default; pass `--no-wait`
+to return as soon as the invocation is accepted, or `--wait-timeout` to bound
+the wait server-side. Pass `--idempotency-key` to make a run retry-safe. The
+JSON output carries the effective `idempotency_key`, whether supplied by the
+caller or generated by the server — absent only if something between the CLI
+and Albus strips the response header on a run that supplied no key.
+
+`--agent-file` takes a JSON object shaped like the API's `AgentConfig` and
+covers what the flags do not (MCP servers, provider URL overrides):
+
+```json
+{
+  "model": { "name": "gemini-3.6-flash" },
+  "mcp_servers": [
+    { "name": "github", "url": "https://mcp.example.com/mcp" }
+  ]
+}
+```
+
+## Documentation
+
+| Reader | URL |
+|---|---|
+| A person | <https://docs.albus.sh> |
+| A coding agent | <https://docs.albus.sh/agents/docs.md> |
+
+The CLI prints both, so whoever is reading its output has the URL that is
+theirs.
+
+## Development
+
+The CLI is developed in the private Albus repository, next to the
+`api/openapi.yaml` contract and the SDK it is built on, and each release is
+copied to the public `albusgroup/albus-cli` repository. That repository accepts
+issues, not pull requests — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+```bash
+make check      # ruff, mypy --strict, pytest
+```