albus-cli 0.1.0__py3-none-any.whl

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/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/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))

albus_cli/commands/secrets.py

@@ -0,0 +1,62 @@
+"""`albus secrets` — manage secrets available to agent sessions."""
+
+import sys
+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="Manage secrets.")
+
+Name = Annotated[str, typer.Argument(metavar="NAME", help="Secret name.")]
+Value = Annotated[
+    str | None,
+    typer.Option(
+        "--value",
+        help="Secret value. Omit to read it from stdin, keeping it out "
+        "of the shell history.",
+    ),
+]
+
+
+def secret_value(value: str | None) -> str:
+    if value is not None:
+        return value
+
+    read = sys.stdin.read().strip()
+    if not read:
+        raise typer.BadParameter("no secret value on stdin")
+
+    return read
+
+
+@app.command("list")
+def list_secrets(ctx: typer.Context) -> None:
+    """List all secrets with masked values."""
+    emit(sdk(ctx).secrets.list_secrets())
+
+
+@app.command("create")
+def create(ctx: typer.Context, name: Name, value: Value = None) -> None:
+    """Create a secret."""
+    emit(sdk(ctx).secrets.create_secret(name=name, value=secret_value(value)))
+
+
+@app.command("get")
+def get(ctx: typer.Context, name: Name) -> None:
+    """Get a secret's masked value."""
+    emit(sdk(ctx).secrets.get_secret(name=name))
+
+
+@app.command("update")
+def update(ctx: typer.Context, name: Name, value: Value = None) -> None:
+    """Replace a secret's value."""
+    emit(sdk(ctx).secrets.update_secret(name=name, value=secret_value(value)))
+
+
+@app.command("delete")
+def delete(ctx: typer.Context, name: Name) -> None:
+    """Delete a secret."""
+    sdk(ctx).secrets.delete_secret(name=name)

albus_cli/commands/sessions.py

@@ -0,0 +1,223 @@
+"""`albus sessions` — run and inspect agent sessions."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from albus_sdk import models
+
+from albus_cli.client import client
+from albus_cli.context import options, sdk
+from albus_cli.output import emit
+
+app = typer.Typer(no_args_is_help=True, help="Run and inspect sessions.")
+
+SessionID = Annotated[
+    str,
+    typer.Argument(
+        metavar="SESSION_ID",
+        help="Client-provided session identifier. Reuse it to continue "
+        "the same session.",
+    ),
+]
+After = Annotated[
+    str | None,
+    typer.Option("--after", help="Pagination cursor from a previous page."),
+]
+Limit = Annotated[int, typer.Option("--limit", help="Page size.")]
+
+
+def agent_config(
+    agent_file: Path | None,
+    model: str | None,
+    provider: str | None,
+    credential: str | None,
+    system_prompt: str | None,
+    tools: list[str],
+    max_steps: int | None,
+) -> models.AgentConfig:
+    if agent_file is not None:
+        flags = (model, provider, credential, system_prompt, max_steps)
+        if any(flag is not None for flag in flags) or tools:
+            raise typer.BadParameter(
+                "--agent-file holds the whole agent configuration and "
+                "cannot be combined with the other agent options"
+            )
+
+        return models.AgentConfig.model_validate_json(agent_file.read_text())
+
+    if model is None:
+        raise typer.BadParameter(
+            "--model is required unless --agent-file is given"
+        )
+
+    if (provider is None) != (credential is None):
+        raise typer.BadParameter(
+            "--provider and --credential must be given together"
+        )
+
+    provider_config = (
+        models.Provider(name=provider, credential=credential)
+        if provider is not None and credential is not None
+        else None
+    )
+
+    return models.AgentConfig(
+        model=models.Model(name=model, provider=provider_config),
+        tools=tools or None,
+        system_prompt=system_prompt,
+        max_steps=max_steps,
+    )
+
+
+@app.command("run")
+def run(
+    ctx: typer.Context,
+    session_id: SessionID,
+    prompt: Annotated[
+        str,
+        typer.Option(
+            "--prompt",
+            "-p",
+            help="The user prompt driving this invocation.",
+        ),
+    ],
+    agent_name: Annotated[
+        str,
+        typer.Option(
+            "--agent-name",
+            help='Name identifying the agent (e.g. "support-triage").',
+        ),
+    ],
+    model: Annotated[
+        str | None,
+        typer.Option(
+            "--model", help='Model identifier (e.g. "gemini-3.6-flash").'
+        ),
+    ] = None,
+    provider: Annotated[
+        str | None,
+        typer.Option("--provider", help='Provider name (e.g. "gemini").'),
+    ] = None,
+    credential: Annotated[
+        str | None,
+        typer.Option(
+            "--credential",
+            help="Secret reference the provider authenticates with "
+            '(e.g. "albus.sh/secrets/my-key").',
+        ),
+    ] = None,
+    system_prompt: Annotated[
+        str | None,
+        typer.Option(
+            "--system-prompt", help="System instructions for the model."
+        ),
+    ] = None,
+    tools: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--tool",
+            help="Tool the model may call. Repeat to allow several.",
+        ),
+    ] = None,
+    max_steps: Annotated[
+        int | None,
+        typer.Option(
+            "--max-steps", help="Max model steps before the run stops."
+        ),
+    ] = None,
+    agent_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--agent-file",
+            exists=True,
+            dir_okay=False,
+            help="JSON file holding the whole agent configuration, for "
+            "configurations the flags do not cover (e.g. MCP servers).",
+        ),
+    ] = None,
+    idempotency_key: Annotated[
+        str | None,
+        typer.Option(
+            "--idempotency-key",
+            help="Identifies this invocation so the call is retry-safe.",
+        ),
+    ] = None,
+    wait: Annotated[
+        bool,
+        typer.Option(
+            "--wait/--no-wait",
+            help="Block until the assistant response is available.",
+        ),
+    ] = True,
+    wait_timeout: Annotated[
+        int | None,
+        typer.Option(
+            "--wait-timeout",
+            help="Seconds to block while waiting. Omit to wait indefinitely.",
+        ),
+    ] = None,
+) -> None:
+    """Run or resume a session."""
+    agent = agent_config(
+        agent_file,
+        model,
+        provider,
+        credential,
+        system_prompt,
+        tools or [],
+        max_steps,
+    )
+    opts = options(ctx)
+    # A waiting run long-polls, so it outlives the request timeout.
+    albus = client(opts.base_url, None if wait else opts.timeout)
+    response = albus.sessions.run_session(
+        id=session_id,
+        user_prompt=prompt,
+        agent_name=agent_name,
+        agent=agent,
+        idempotency_key=idempotency_key,
+        wait=wait,
+        wait_timeout=wait_timeout,
+    )
+    result = response.result.model_dump(mode="json", exclude_none=True)
+    result["idempotency_key"] = response.headers["idempotency-key"][0]
+    emit(result)
+
+
+@app.command("list")
+def list_sessions(ctx: typer.Context) -> None:
+    """List all sessions."""
+    emit(sdk(ctx).sessions.list_sessions())
+
+
+@app.command("get")
+def get(
+    ctx: typer.Context,
+    session_id: SessionID,
+    after: After = None,
+    limit: Limit = 100,
+) -> None:
+    """Get a session with a page of its messages."""
+    emit(sdk(ctx).sessions.get_session(id=session_id, after=after, limit=limit))
+
+
+@app.command("audit")
+def audit(
+    ctx: typer.Context,
+    session_id: SessionID,
+    after: After = None,
+    limit: Limit = 100,
+) -> None:
+    """List a page of a session's audit log."""
+    emit(
+        sdk(ctx).sessions.get_session_audit(
+            id=session_id, after=after, limit=limit
+        )
+    )
+
+
+@app.command("delete")
+def delete(ctx: typer.Context, session_id: SessionID) -> None:
+    """Delete a session."""
+    sdk(ctx).sessions.delete_session(id=session_id)

albus_cli/context.py

@@ -0,0 +1,24 @@
+"""Global options shared by every command."""
+
+from dataclasses import dataclass
+from typing import cast
+
+import typer
+from albus_sdk import Albus
+
+from albus_cli.client import client
+
+
+@dataclass(frozen=True)
+class Options:
+    base_url: str | None
+    timeout: float
+
+
+def options(ctx: typer.Context) -> Options:
+    return cast(Options, ctx.obj)
+
+
+def sdk(ctx: typer.Context) -> Albus:
+    opts = options(ctx)
+    return client(opts.base_url, opts.timeout)

albus_cli/main.py

@@ -0,0 +1,63 @@
+"""`albus` — command-line client for the Albus REST API."""
+
+from typing import Annotated
+
+import httpx
+import typer
+from albus_sdk import errors
+
+from albus_cli.client import BASE_URL_ENV, MissingAPIKey
+from albus_cli.commands import agents, secrets, sessions
+from albus_cli.context import Options, sdk
+from albus_cli.output import emit
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    help="Command-line client for the Albus REST API. Authenticates with "
+    "the API key in ALBUS_API_KEY and prints JSON responses.",
+)
+app.add_typer(sessions.app, name="sessions")
+app.add_typer(secrets.app, name="secrets")
+app.add_typer(agents.app, name="agents")
+
+
+@app.callback()
+def configure(
+    ctx: typer.Context,
+    base_url: Annotated[
+        str | None,
+        typer.Option(
+            "--base-url",
+            envvar=BASE_URL_ENV,
+            help="Albus API base URL. Defaults to production.",
+        ),
+    ] = None,
+    timeout: Annotated[
+        float,
+        typer.Option("--timeout", help="Request timeout in seconds."),
+    ] = 30.0,
+) -> None:
+    ctx.obj = Options(base_url=base_url, timeout=timeout)
+
+
+@app.command("health")
+def health(ctx: typer.Context) -> None:
+    """Check service availability."""
+    emit(sdk(ctx).health.health())
+
+
+def main() -> None:
+    try:
+        app()
+    except MissingAPIKey as missing:
+        fail(str(missing))
+    except errors.AlbusError as error:
+        fail(f"{error.status_code}: {error.message}")
+    except httpx.HTTPError as transport:
+        fail(str(transport))
+
+
+def fail(message: str) -> None:
+    typer.secho(f"albus: {message}", fg=typer.colors.RED, err=True)
+    raise SystemExit(1)

albus_cli/output.py

@@ -0,0 +1,16 @@
+"""Command output. Every command prints one pretty-printed JSON value."""
+
+import json
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def emit(value: BaseModel | list[Any] | dict[str, Any] | None) -> None:
+    if value is None:
+        return
+
+    if isinstance(value, BaseModel):
+        value = value.model_dump(mode="json", exclude_none=True)
+
+    print(json.dumps(value, indent=2))

albus_cli-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+albus_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+albus_cli/__main__.py,sha256=oJAekektwsWMaeZVHcR7YcFSHlrCloXQHP_j5AcfsH0,117
+albus_cli/client.py,sha256=Q18fv9CvCK99VgNINHmkwrDypAlePMovtzUPuIDyLlc,818
+albus_cli/context.py,sha256=xgIgwQ8-tkNxWEEVhcjplPgNgim5P3u91e_ur2s5UEE,460
+albus_cli/main.py,sha256=Wlpj1Fn816eQ4HfhrOYv9WeIQk5c6fuEih2_YHRJ2OM,1682
+albus_cli/output.py,sha256=ECRO5OPqF7PjgnvdLyv8amTKBrxMiS3SksGmmzhuIuc,396
+albus_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+albus_cli/commands/agents.py,sha256=WuSXfbqyECvxikne60b9U7XBFcCcD-QNaS95MWSyA8o,980
+albus_cli/commands/secrets.py,sha256=BJLt2bn_2-LWi-Xh5klhO2q1RHx6_PMMezIuUW0SfBY,1631
+albus_cli/commands/sessions.py,sha256=IQZmKppSRAhcHUCvNboYOkw2L7vWAvl0imWjnsxvBlQ,6144
+albus_cli-0.1.0.dist-info/METADATA,sha256=2dD0Oj8n-UszHSeanmDc_H4L1x6GFOx9b4besWDrj-c,2570
+albus_cli-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+albus_cli-0.1.0.dist-info/entry_points.txt,sha256=9g6sVxZtR__IY9Nvk7aaLh8S6cxUWSxwyKHiQMEweG4,46
+albus_cli-0.1.0.dist-info/licenses/LICENSE,sha256=DNMiLr-P9bczooicuwDQOU04-9XSjT0NWwAJhBmE1Bk,1062
+albus_cli-0.1.0.dist-info/RECORD,,

albus_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

albus_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+albus = albus_cli.main:main

albus_cli-0.1.0.dist-info/licenses/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.