albus-cli 0.1.0__tar.gz

albus_cli-0.1.0/.github/workflows/check.yml

@@ -0,0 +1,32 @@
+name: Check
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    env:
+      NO_COLOR: "1"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Check
+        run: ./tools/check
+
+      - name: Assert pure-Python wheel
+        run: |
+          rm -rf dist
+          uv build
+          wheel=$(echo dist/*.whl)
+          case "$(basename "$wheel")" in
+            *-py3-none-any.whl) echo "ok: $wheel" ;;
+            *) echo "error: expected py3-none-any, got $wheel" >&2; exit 1 ;;
+          esac

albus_cli-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+.tmp/

albus_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Albus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

albus_cli-0.1.0/Makefile

@@ -0,0 +1,19 @@
+.PHONY: install lint fmt typecheck test check
+
+install:
+	uv sync
+
+lint: install
+	uv run ruff check .
+	uv run ruff format --check .
+
+fmt: install
+	uv run ruff format .
+
+typecheck: install
+	uv run mypy
+
+test: install
+	uv run pytest
+
+check: lint typecheck test

albus_cli-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: albus-cli
+Version: 0.1.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.4.0
+Requires-Dist: typer<0.28,>=0.26.8
+Description-Content-Type: text/markdown
+
+# albus CLI
+
+Command-line client for the Albus REST API. Thin shell over the public
+[`albus-sdk`](https://pypi.org/project/albus-sdk/) Python package: every
+command maps to one API operation and prints JSON (pipe 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
+ALBUS_CLI_VERSION=0.1.0 curl -fsSL https://raw.githubusercontent.com/albusgroup/albus-cli/master/install.sh | sh
+```
+
+The installer uses, in order: `uv tool install`, `pip install --user`, or
+`pip` inside a conda environment. It does not download OS-specific Albus
+binaries and does not check OS versions.
+
+You can also install directly:
+
+```bash
+uv tool install albus-cli
+# or
+pip install --user albus-cli
+```
+
+## Authentication
+
+```bash
+export ALBUS_API_KEY=...     # organization API key
+export ALBUS_BASE_URL=...    # optional; defaults to production
+```
+
+`--base-url` overrides `ALBUS_BASE_URL`, and `--timeout` bounds each request
+(a waiting `sessions run` long-polls and is exempt).
+
+The API key is the only credential, so the CLI covers only the operations that
+accept `apiKeyAuth`.
+
+## Commands
+
+```bash
+albus health
+
+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 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 ...
+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"
+```
+
+## Development
+
+```bash
+make install
+make check      # ruff, mypy --strict, pytest
+```
+
+See [RELEASING.md](RELEASING.md) to publish a PyPI version.

albus_cli-0.1.0/README.md

@@ -0,0 +1,83 @@
+# albus CLI
+
+Command-line client for the Albus REST API. Thin shell over the public
+[`albus-sdk`](https://pypi.org/project/albus-sdk/) Python package: every
+command maps to one API operation and prints JSON (pipe 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
+ALBUS_CLI_VERSION=0.1.0 curl -fsSL https://raw.githubusercontent.com/albusgroup/albus-cli/master/install.sh | sh
+```
+
+The installer uses, in order: `uv tool install`, `pip install --user`, or
+`pip` inside a conda environment. It does not download OS-specific Albus
+binaries and does not check OS versions.
+
+You can also install directly:
+
+```bash
+uv tool install albus-cli
+# or
+pip install --user albus-cli
+```
+
+## Authentication
+
+```bash
+export ALBUS_API_KEY=...     # organization API key
+export ALBUS_BASE_URL=...    # optional; defaults to production
+```
+
+`--base-url` overrides `ALBUS_BASE_URL`, and `--timeout` bounds each request
+(a waiting `sessions run` long-polls and is exempt).
+
+The API key is the only credential, so the CLI covers only the operations that
+accept `apiKeyAuth`.
+
+## Commands
+
+```bash
+albus health
+
+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 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 ...
+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"
+```
+
+## Development
+
+```bash
+make install
+make check      # ruff, mypy --strict, pytest
+```
+
+See [RELEASING.md](RELEASING.md) to publish a PyPI version.

albus_cli-0.1.0/RELEASING.md

@@ -0,0 +1,59 @@
+# Releasing the Albus CLI
+
+Releases are intentionally manual during the MVP. The repository provides a
+guarded publisher; it does not create commits, tags, or PyPI credentials.
+
+## One-time PyPI setup
+
+1. Create a PyPI account, verify email, enable 2FA, and save recovery codes.
+2. Create the `albus-cli` project (first upload) or ask an owner to add you.
+3. Create an API token limited to the `albus-cli` project and store it in a
+   password manager.
+
+TestPyPI has separate accounts and tokens.
+
+Never put an API token in this repository, a command-line argument, shell
+history, or a pull request.
+
+## Choose a version
+
+Use a normalized PEP 440 version. Bump `project.version` in `pyproject.toml`
+and pin `albus-sdk` to the intended public SDK release before publishing.
+
+Published versions cannot be reused.
+
+## Prepare a release
+
+1. Sync package sources from the private monorepo `cli/` if development
+   happened there.
+2. Update `version` and the `albus-sdk==…` pin in `pyproject.toml`.
+3. Merge to `master` on a clean tree.
+4. Validate:
+
+   ```bash
+   ./tools/publish --dry-run 0.1.0
+   ```
+
+## Publish
+
+```bash
+read -s UV_PUBLISH_TOKEN
+export UV_PUBLISH_TOKEN
+./tools/publish 0.1.0
+unset UV_PUBLISH_TOKEN
+```
+
+TestPyPI:
+
+```bash
+./tools/publish --testpypi 0.1.0
+```
+
+Verify:
+
+```bash
+uv tool install albus-cli==0.1.0
+albus --help
+```
+
+Or exercise the public installer after the release is visible on PyPI.

albus_cli-0.1.0/install.ps1

@@ -0,0 +1,110 @@
+# Install the Albus CLI (albus) from PyPI.
+# Prefers uv, then pip --user, then pip inside a conda env.
+# Usage:
+#   irm https://raw.githubusercontent.com/albusgroup/albus-cli/master/install.ps1 | iex
+# Optional:
+#   $env:ALBUS_CLI_VERSION = "0.1.0"
+
+$ErrorActionPreference = "Stop"
+
+$Package = "albus-cli"
+$Version = $env:ALBUS_CLI_VERSION
+if ([string]::IsNullOrEmpty($Version)) {
+    $Spec = $Package
+} else {
+    $Spec = "$Package==$Version"
+}
+
+function Test-Command($Name) {
+    return $null -ne (Get-Command $Name -ErrorAction SilentlyContinue)
+}
+
+function Get-PipCommand {
+    if (Test-Command "py") {
+        try {
+            & py -m pip --version | Out-Null
+            if ($LASTEXITCODE -eq 0) { return @("py", "-m", "pip") }
+        } catch {}
+    }
+    if (Test-Command "python") {
+        try {
+            & python -m pip --version | Out-Null
+            if ($LASTEXITCODE -eq 0) { return @("python", "-m", "pip") }
+        } catch {}
+    }
+    if (Test-Command "python3") {
+        try {
+            & python3 -m pip --version | Out-Null
+            if ($LASTEXITCODE -eq 0) { return @("python3", "-m", "pip") }
+        } catch {}
+    }
+    return $null
+}
+
+function Install-WithUv {
+    Write-Host "Installing $Spec with uv tool install..."
+    & uv tool install $Spec
+    if ($LASTEXITCODE -ne 0) { throw "uv tool install failed" }
+    Write-Host "Installed with uv. Ensure the uv tool bin directory is on PATH."
+}
+
+function Install-WithPip {
+    $pip = Get-PipCommand
+    if ($null -eq $pip) { return $false }
+    Write-Host "Installing $Spec with $($pip -join ' ') --user..."
+    & $pip[0] $pip[1..($pip.Length - 1)] install --user $Spec
+    if ($LASTEXITCODE -ne 0) { throw "pip install failed" }
+    Write-Host "Installed with pip --user. Ensure your user Scripts directory is on PATH."
+    return $true
+}
+
+function Install-WithConda {
+    if (-not (Test-Command "conda")) { return $false }
+
+    if (-not [string]::IsNullOrEmpty($env:CONDA_PREFIX)) {
+        $envPython = Join-Path $env:CONDA_PREFIX "python.exe"
+        $envLabel = $env:CONDA_PREFIX
+    } else {
+        $base = (& conda info --base).Trim()
+        $envPython = Join-Path $base "python.exe"
+        $envLabel = $base
+    }
+
+    if (-not (Test-Path $envPython)) {
+        throw "conda found but Python is missing at $envPython"
+    }
+
+    try {
+        & $envPython -m pip --version | Out-Null
+        if ($LASTEXITCODE -ne 0) { throw "pip missing" }
+    } catch {
+        Write-Host "pip missing in conda env; installing pip via conda..."
+        & conda install -y pip
+        if ($LASTEXITCODE -ne 0) { throw "conda install pip failed" }
+    }
+
+    Write-Host "Installing $Spec with pip into conda env ($envLabel)..."
+    & $envPython -m pip install $Spec
+    if ($LASTEXITCODE -ne 0) { throw "conda env pip install failed" }
+    Write-Host "Installed into the conda env. Activate that env to run albus."
+    return $true
+}
+
+if (Test-Command "uv") {
+    Install-WithUv
+} elseif (Install-WithPip) {
+    # done
+} elseif (Install-WithConda) {
+    # done
+} else {
+    throw "need uv, pip, or conda on PATH. Install one of them, then re-run."
+}
+
+if (Test-Command "albus") {
+    Write-Host "Running: albus --help"
+    & albus --help
+} else {
+    Write-Host "albus is installed but not on PATH yet. Open a new shell or add the scripts directory to PATH, then run: albus --help"
+}
+
+Write-Host "Set ALBUS_API_KEY before calling the API."

albus_cli-0.1.0/install.sh

@@ -0,0 +1,111 @@
+#!/bin/sh
+# Install the Albus CLI (albus) from PyPI.
+# Prefers uv, then pip --user, then pip inside a conda env.
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/albusgroup/albus-cli/master/install.sh | sh
+# Optional:
+#   ALBUS_CLI_VERSION=0.1.0 curl -fsSL ... | sh
+
+set -eu
+
+PACKAGE="albus-cli"
+VERSION="${ALBUS_CLI_VERSION:-}"
+
+spec="$PACKAGE"
+if [ -n "$VERSION" ]; then
+    spec="${PACKAGE}==${VERSION}"
+fi
+
+say() {
+    printf '%s\n' "$*"
+}
+
+err() {
+    printf 'error: %s\n' "$*" >&2
+}
+
+have() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+pip_cmd() {
+    if have python3; then
+        if python3 -m pip --version >/dev/null 2>&1; then
+            printf '%s\n' "python3 -m pip"
+            return 0
+        fi
+    fi
+    if have python; then
+        if python -m pip --version >/dev/null 2>&1; then
+            printf '%s\n' "python -m pip"
+            return 0
+        fi
+    fi
+    return 1
+}
+
+install_with_uv() {
+    say "Installing ${spec} with uv tool install..."
+    uv tool install "$spec"
+    say "Installed with uv. Ensure the uv tool bin directory is on your PATH"
+    say "(usually ~/.local/bin)."
+}
+
+install_with_pip() {
+    cmd=$(pip_cmd) || return 1
+    say "Installing ${spec} with ${cmd} --user..."
+    # shellcheck disable=SC2086
+    $cmd install --user "$spec"
+    say "Installed with pip --user. Ensure your user scripts directory is on"
+    say "PATH (often ~/.local/bin on Unix)."
+}
+
+install_with_conda() {
+    have conda || return 1
+
+    if [ -n "${CONDA_PREFIX:-}" ]; then
+        env_python="${CONDA_PREFIX}/bin/python"
+        env_label="$CONDA_PREFIX"
+    else
+        base_prefix=$(conda info --base 2>/dev/null) || return 1
+        env_python="${base_prefix}/bin/python"
+        env_label="$base_prefix"
+    fi
+
+    if [ ! -x "$env_python" ]; then
+        err "conda found but Python is missing at ${env_python}"
+        return 1
+    fi
+
+    if ! "$env_python" -m pip --version >/dev/null 2>&1; then
+        say "pip missing in conda env; installing pip via conda..."
+        conda install -y pip
+    fi
+
+    say "Installing ${spec} with pip into conda env (${env_label})..."
+    "$env_python" -m pip install "$spec"
+    say "Installed into the conda env. Activate that env (or ensure its"
+    say "bin/Scripts directory is on PATH) to run albus."
+}
+
+if have uv; then
+    install_with_uv
+elif pip_cmd >/dev/null 2>&1; then
+    install_with_pip
+elif have conda; then
+    install_with_conda
+else
+    err "need uv, pip, or conda on PATH"
+    err "Install one of them, then re-run this script."
+    exit 1
+fi
+
+if have albus; then
+    say "Running: albus --help"
+    albus --help
+else
+    say "albus is installed but not on PATH yet. Open a new shell or add"
+    say "the scripts directory reported above to PATH, then run: albus --help"
+fi
+
+say "Set ALBUS_API_KEY before calling the API."

albus_cli-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "albus-cli"
+version = "0.1.0"
+description = "Command-line client for the Albus REST API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Albus" }]
+dependencies = [
+    "albus-sdk==0.4.0",
+    "typer>=0.26.8,<0.28",
+]
+
+[project.urls]
+Homepage = "https://github.com/albusgroup/albus-cli"
+Repository = "https://github.com/albusgroup/albus-cli"
+Issues = "https://github.com/albusgroup/albus-cli/issues"
+
+[project.scripts]
+albus = "albus_cli.main:main"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.17,<2",
+    "pytest>=8.4,<10",
+    "ruff>=0.16,<0.17",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/albus_cli"]
+
+[tool.ruff]
+line-length = 81
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["albus_cli", "tests"]
+
+[tool.mypy]
+python_version = "3.11"
+files = ["src", "tests"]
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

albus_cli-0.1.0/src/albus_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m albus_cli`."""
+
+from albus_cli.main import main
+
+if __name__ == "__main__":
+    main()

albus_cli-0.1.0/src/albus_cli/client.py

@@ -0,0 +1,30 @@
+"""Albus SDK client construction from the shell environment."""
+
+import os
+
+import httpx
+from albus_sdk import Albus, models
+
+API_KEY_ENV = "ALBUS_API_KEY"
+BASE_URL_ENV = "ALBUS_BASE_URL"
+
+
+class MissingAPIKey(Exception):
+    def __init__(self) -> None:
+        super().__init__(
+            f"{API_KEY_ENV} is not set. Export an Albus API key, e.g. "
+            f"`export {API_KEY_ENV}=...`."
+        )
+
+
+def client(base_url: str | None, timeout: float | None) -> Albus:
+    """Build an SDK client. A timeout of None disables the read timeout."""
+    api_key = os.environ.get(API_KEY_ENV)
+    if not api_key:
+        raise MissingAPIKey
+
+    return Albus(
+        security=models.Security(api_key_auth=api_key),
+        server_url=base_url,
+        client=httpx.Client(follow_redirects=True, timeout=timeout),
+    )

albus_cli-0.1.0/src/albus_cli/commands/agents.py

@@ -0,0 +1,39 @@
+"""`albus agents` — inspect the agents that have run in the org."""
+
+from typing import Annotated
+
+import typer
+
+from albus_cli.context import sdk
+from albus_cli.output import emit
+
+app = typer.Typer(no_args_is_help=True, help="Inspect agents.")
+
+AgentName = Annotated[
+    str, typer.Argument(metavar="AGENT_NAME", help="Agent name.")
+]
+
+
+@app.command("list")
+def list_agents(ctx: typer.Context) -> None:
+    """List agents."""
+    emit(sdk(ctx).agents.list_agents())
+
+
+@app.command("get")
+def get(ctx: typer.Context, name: AgentName) -> None:
+    """Get an agent with its current revision."""
+    emit(sdk(ctx).agents.get_agent(name=name))
+
+
+@app.command("revision")
+def revision(
+    ctx: typer.Context,
+    name: AgentName,
+    revision: Annotated[
+        str,
+        typer.Argument(metavar="REVISION", help="Agent revision identifier."),
+    ],
+) -> None:
+    """Get one revision of an agent."""
+    emit(sdk(ctx).agents.get_agent_revision(name=name, revision=revision))