current-cli 0.1.0__tar.gz

current_cli-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Django
+*.pyc
+__pycache__/
+db.sqlite3
+media/
+staticfiles/
+
+# Python
+.venv/
+.env
+.ruff_cache/
+.pytest_cache/
+.vscode/
+.DS_Store
+
+uv.lock
+
+# Kea typegen output
+**/*LogicType.ts
+
+# Node
+node_modules/
+dist/

current_cli-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: current-cli
+Version: 0.1.0
+Summary: Command line interface for the Current API, generated from its OpenAPI schema at runtime
+Author-email: Orin <your-email@example.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# current-cli
+
+Command line interface for the Current API. Commands are generated at runtime
+from the bundled OpenAPI schema, so every API operation is available without
+per-endpoint code.
+
+## Install
+
+```bash
+pip install current-cli
+```
+
+Or from a repo checkout:
+
+```bash
+cd cli && uv sync
+```
+
+## Usage
+
+```bash
+current config set base_url https://your-api.example.com
+current login you@example.com
+current config set default_workspace <workspace-uuid>
+
+current projects list
+current projects retrieve <id>
+current tasks create --data '{"name": "Order beams", "workspace": "..."}'
+current workspaces members list <workspace_id>
+```
+
+Run `current --help` (or `--help` on any subcommand) to see everything the
+API exposes. `current docs` prints a markdown reference of every command;
+the committed copy lives at [llms.txt](llms.txt) — hand it to an LLM that
+needs to drive the CLI.
+
+## Development
+
+```bash
+cd cli
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+The bundled schema (`current_cli/schema.yml`) is a copy of `api/schema.yml`,
+kept in sync by `api/scripts/generate.sh`. Point the CLI at a different schema
+with `--schema <path-or-url>` or `CURRENT_SCHEMA`.

current_cli-0.1.0/README.md

@@ -0,0 +1,48 @@
+# current-cli
+
+Command line interface for the Current API. Commands are generated at runtime
+from the bundled OpenAPI schema, so every API operation is available without
+per-endpoint code.
+
+## Install
+
+```bash
+pip install current-cli
+```
+
+Or from a repo checkout:
+
+```bash
+cd cli && uv sync
+```
+
+## Usage
+
+```bash
+current config set base_url https://your-api.example.com
+current login you@example.com
+current config set default_workspace <workspace-uuid>
+
+current projects list
+current projects retrieve <id>
+current tasks create --data '{"name": "Order beams", "workspace": "..."}'
+current workspaces members list <workspace_id>
+```
+
+Run `current --help` (or `--help` on any subcommand) to see everything the
+API exposes. `current docs` prints a markdown reference of every command;
+the committed copy lives at [llms.txt](llms.txt) — hand it to an LLM that
+needs to drive the CLI.
+
+## Development
+
+```bash
+cd cli
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+The bundled schema (`current_cli/schema.yml`) is a copy of `api/schema.yml`,
+kept in sync by `api/scripts/generate.sh`. Point the CLI at a different schema
+with `--schema <path-or-url>` or `CURRENT_SCHEMA`.

current_cli-0.1.0/current_cli/__init__.py

@@ -0,0 +1 @@
+"""Command line interface for the Current API, generated from its OpenAPI schema."""

current_cli-0.1.0/current_cli/build.py

@@ -0,0 +1,86 @@
+"""Turn OpenAPI operations into a nested tree of click commands."""
+
+from __future__ import annotations
+
+import click
+
+from . import config, http
+from .schema import Operation
+
+
+def _make_callback(op: Operation):
+    def callback(**kwargs):
+        data = kwargs.pop("data", None)
+
+        path = op.path
+        for param in op.path_params:
+            path = path.replace("{" + param.name + "}", str(kwargs.pop(param.name)))
+
+        params: dict[str, str] = {}
+        for param in op.query_params:
+            value = kwargs.pop(param.name, None)
+            if value is None and param.name == "workspace":
+                value = config.get("default_workspace")
+            if value is None:
+                if param.required:
+                    hint = (
+                        " (or set a default: current config set default_workspace <uuid>)"
+                        if param.name == "workspace"
+                        else ""
+                    )
+                    raise click.UsageError(f"Missing required option --{param.name}{hint}.")
+                continue
+            params[param.name] = value
+
+        json_body = http.parse_data_argument(data) if data is not None else None
+        response = http.request(op.method, path, params=params, json_body=json_body)
+        http.render_response(response)
+
+    return callback
+
+
+def _make_command(op: Operation) -> click.Command:
+    params: list[click.Parameter] = [click.Argument([param.name]) for param in op.path_params]
+    for param in op.query_params:
+        # Required query params are enforced in the callback so that
+        # `workspace` can fall back to the configured default.
+        params.append(
+            click.Option(
+                [f"--{param.name.replace('_', '-')}"],
+                required=False,
+                help=param.description or None,
+            )
+        )
+    if op.has_body:
+        params.append(
+            click.Option(
+                ["--data"],
+                required=op.method in ("post", "put", "patch"),
+                help="Request body as JSON: inline, @file.json, or - for stdin.",
+            )
+        )
+
+    help_text = f"{op.description}\n\n{op.method.upper()} {op.path}".strip()
+    return click.Command(
+        name=op.command,
+        params=params,
+        callback=_make_callback(op),
+        help=help_text,
+        short_help=op.description.split("\n")[0] if op.description else None,
+    )
+
+
+def add_operations(root: click.Group, operations: list[Operation]) -> None:
+    for op in operations:
+        group = root
+        for segment in op.group_path:
+            existing = group.commands.get(segment)
+            if existing is None:
+                existing = click.Group(name=segment, help=f"Operations under /{segment}/.")
+                group.add_command(existing)
+            elif not isinstance(existing, click.Group):
+                raise RuntimeError(
+                    f"Command tree conflict: {segment} is both a group and a command"
+                )
+            group = existing
+        group.add_command(_make_command(op))

current_cli-0.1.0/current_cli/config.py

@@ -0,0 +1,54 @@
+"""Persistent CLI configuration (auth token, base URL, default workspace)."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+DEFAULT_BASE_URL = "http://localhost:8000"
+KNOWN_KEYS = ("base_url", "token", "email", "default_workspace")
+
+
+def config_dir() -> Path:
+    override = os.environ.get("CURRENT_CLI_CONFIG_DIR")
+    if override:
+        return Path(override)
+    return Path.home() / ".config" / "current-cli"
+
+
+def config_path() -> Path:
+    return config_dir() / "config.json"
+
+
+def load() -> dict:
+    path = config_path()
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text("utf-8"))
+
+
+def save(data: dict) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", "utf-8")
+
+
+def get(key: str) -> str | None:
+    return load().get(key)
+
+
+def set_value(key: str, value: str) -> None:
+    data = load()
+    data[key] = value
+    save(data)
+
+
+def unset(key: str) -> None:
+    data = load()
+    data.pop(key, None)
+    save(data)
+
+
+def base_url() -> str:
+    return os.environ.get("CURRENT_API_URL") or get("base_url") or DEFAULT_BASE_URL

current_cli-0.1.0/current_cli/docs.py

@@ -0,0 +1,83 @@
+"""Render the full command tree as markdown, for LLMs and humans.
+
+The committed cli/llms.txt is generated from this module; a test fails if it
+is stale. Regenerate with: uv run python -m current_cli.docs > llms.txt
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+import click
+
+PREAMBLE = """\
+# Current CLI reference
+
+`current` is the command line interface for the Current API. Commands are
+generated from the API's OpenAPI schema, so every API operation is available.
+
+## Setup
+
+```bash
+pip install current-cli
+current config set base_url https://your-api.example.com   # default: http://localhost:8000
+current login you@example.com                              # magic-link sign in, stores the token
+current config set default_workspace <workspace-uuid>      # used when --workspace is omitted
+```
+
+The auth token is stored in `~/.config/current-cli/config.json` and sent as
+`Authorization: Token <token>`. `CURRENT_API_URL` overrides the base URL.
+
+## Conventions
+
+- Path parameters are positional arguments, shown below as `<name>`.
+- Query parameters are `--options`.
+- Request bodies are JSON, passed with `--data`: inline (`--data '{"name": "x"}'`),
+  from a file (`--data @body.json`), or from stdin (`--data -`).
+- Responses print as JSON on stdout. API errors print to stderr and exit 1.
+- `--schema <path-or-url>` (or `CURRENT_SCHEMA`) rebuilds the commands from a
+  different schema, for example `<base-url>/api/schema/` for a live server.
+- Every command supports `--help`.
+
+## Commands"""
+
+
+def _iter_commands(
+    command: click.Command, path: list[str]
+) -> Iterator[tuple[list[str], click.Command]]:
+    if isinstance(command, click.Group):
+        for name in sorted(command.commands):
+            yield from _iter_commands(command.commands[name], [*path, name])
+    else:
+        yield path, command
+
+
+def render_docs(root: click.Group) -> str:
+    sections = [PREAMBLE]
+    for path, command in _iter_commands(root, ["current"]):
+        arguments = [p for p in command.params if isinstance(p, click.Argument)]
+        options = [p for p in command.params if isinstance(p, click.Option) and p.name != "help"]
+
+        usage = " ".join([*path, *(f"<{a.name}>" for a in arguments)])
+        lines = [f"### {usage}"]
+        if command.help:
+            lines.append("")
+            lines.append(command.help.strip())
+        if options:
+            lines.append("")
+            lines.append("Options:")
+            for option in options:
+                parts = [f"- `{option.opts[0]}`"]
+                if option.required:
+                    parts.append("(required)")
+                if option.help:
+                    parts.append(f"- {option.help}")
+                lines.append(" ".join(parts))
+        sections.append("\n".join(lines))
+    return "\n\n".join(sections) + "\n"
+
+
+if __name__ == "__main__":
+    from .main import build_cli
+
+    print(render_docs(build_cli()), end="")

current_cli-0.1.0/current_cli/http.py

@@ -0,0 +1,72 @@
+"""HTTP layer: authenticated requests and response rendering."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+import httpx
+from rich.console import Console
+
+from . import config
+
+# Test hook: when set, all requests go through this transport instead of the network.
+TRANSPORT: httpx.BaseTransport | None = None
+
+
+def request(
+    method: str,
+    path: str,
+    *,
+    params: dict | None = None,
+    json_body: dict | list | None = None,
+    authenticated: bool = True,
+) -> httpx.Response:
+    headers = {}
+    if authenticated:
+        token = config.get("token")
+        if token:
+            headers["Authorization"] = f"Token {token}"
+    with httpx.Client(
+        base_url=config.base_url(),
+        headers=headers,
+        timeout=30,
+        transport=TRANSPORT,
+    ) as client:
+        return client.request(method.upper(), path, params=params, json=json_body)
+
+
+def render_response(response: httpx.Response) -> None:
+    """Print the response body and exit non-zero on API errors."""
+    if response.status_code >= 400:
+        click.echo(f"Error: HTTP {response.status_code}", err=True)
+        if response.content:
+            click.echo(response.text, err=True)
+        raise SystemExit(1)
+    if not response.content:
+        return
+    try:
+        data = response.json()
+    except json.JSONDecodeError:
+        click.echo(response.text)
+        return
+    if sys.stdout.isatty():
+        Console().print_json(json.dumps(data))
+    else:
+        click.echo(json.dumps(data, indent=2))
+
+
+def parse_data_argument(value: str) -> dict | list:
+    """Parse --data as inline JSON, @file, or - for stdin."""
+    if value == "-":
+        raw = sys.stdin.read()
+    elif value.startswith("@"):
+        with open(value[1:], encoding="utf-8") as f:
+            raw = f.read()
+    else:
+        raw = value
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise click.UsageError(f"--data is not valid JSON: {exc}") from exc

current_cli-0.1.0/current_cli/main.py

@@ -0,0 +1,159 @@
+"""CLI entry point: static auth/config commands plus schema-generated commands."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import click
+
+from . import config as config_store
+from . import http
+from .build import add_operations
+from .schema import extract_operations, load_spec
+
+MAGIC_LINK_PATH = "/api/accounts/auth/magic-link/"
+VERIFY_PATH = "/api/accounts/auth/verify/"
+LOGOUT_PATH = "/api/accounts/auth/logout/"
+ME_PATH = "/api/accounts/auth/me/"
+
+
+@click.command()
+@click.argument("email")
+def login(email: str) -> None:
+    """Sign in with a magic link and store the auth token."""
+    response = http.request(
+        "post", MAGIC_LINK_PATH, json_body={"email": email}, authenticated=False
+    )
+    if response.status_code >= 400:
+        http.render_response(response)
+        return
+
+    magic_token = response.json().get("debug_token")
+    if magic_token:
+        click.echo("Using debug token from the API (DEBUG mode).")
+    else:
+        click.echo(f"Magic link sent to {email}.")
+        magic_token = click.prompt("Paste the token from the sign-in link")
+
+    verify = http.request(
+        "post", VERIFY_PATH, json_body={"token": magic_token}, authenticated=False
+    )
+    if verify.status_code >= 400:
+        http.render_response(verify)
+        return
+
+    payload = verify.json()
+    config_store.set_value("token", payload["token"])
+    config_store.set_value("email", email)
+    click.echo(f"Logged in as {email}.")
+
+
+@click.command()
+def logout() -> None:
+    """Invalidate the auth token on the server and forget it locally."""
+    if config_store.get("token"):
+        response = http.request("post", LOGOUT_PATH)
+        if response.status_code >= 400:
+            click.echo(f"Server logout failed (HTTP {response.status_code}).", err=True)
+    config_store.unset("token")
+    config_store.unset("email")
+    click.echo("Logged out.")
+
+
+@click.command()
+def whoami() -> None:
+    """Show the current user and workspace memberships."""
+    http.render_response(http.request("get", ME_PATH))
+
+
+@click.command()
+def docs() -> None:
+    """Print a markdown reference of every command, for LLMs and humans."""
+    from .docs import render_docs
+
+    root = click.get_current_context().find_root().command
+    assert isinstance(root, click.Group)
+    click.echo(render_docs(root), nl=False)
+
+
+@click.group(name="config")
+def config_group() -> None:
+    """Read and write CLI configuration."""
+
+
+@config_group.command(name="list")
+def config_list() -> None:
+    """Show all configuration values."""
+    data = config_store.load()
+    if "token" in data:
+        data["token"] = data["token"][:6] + "..."
+    for key, value in sorted(data.items()):
+        click.echo(f"{key} = {value}")
+
+
+@config_group.command(name="get")
+@click.argument("key", type=click.Choice(config_store.KNOWN_KEYS))
+def config_get(key: str) -> None:
+    """Print one configuration value."""
+    value = config_store.get(key)
+    if value is None:
+        raise SystemExit(1)
+    click.echo(value)
+
+
+@config_group.command(name="set")
+@click.argument("key", type=click.Choice(config_store.KNOWN_KEYS))
+@click.argument("value")
+def config_set(key: str, value: str) -> None:
+    """Set one configuration value."""
+    config_store.set_value(key, value)
+    click.echo(f"{key} = {value}")
+
+
+@config_group.command(name="unset")
+@click.argument("key", type=click.Choice(config_store.KNOWN_KEYS))
+def config_unset(key: str) -> None:
+    """Remove one configuration value."""
+    config_store.unset(key)
+    click.echo(f"{key} unset")
+
+
+def build_cli(schema_source: str | None = None) -> click.Group:
+    spec = load_spec(schema_source or os.environ.get("CURRENT_SCHEMA"))
+    root = click.Group(
+        name="current",
+        help=(
+            "Command line interface for the Current API.\n\n"
+            "API commands are generated from the OpenAPI schema. Pass --schema "
+            "<path-or-url> (or set CURRENT_SCHEMA) to use a different schema, "
+            "for example <base-url>/api/schema/ for a live server."
+        ),
+    )
+    root.add_command(login)
+    root.add_command(logout)
+    root.add_command(whoami)
+    root.add_command(docs)
+    root.add_command(config_group)
+    add_operations(root, extract_operations(spec))
+    return root
+
+
+def main() -> None:
+    # --schema must be handled before click parses anything, because it
+    # determines the command tree itself.
+    argv = list(sys.argv[1:])
+    schema_source = None
+    if "--schema" in argv:
+        index = argv.index("--schema")
+        if index + 1 >= len(argv):
+            click.echo("Error: --schema requires a value.", err=True)
+            raise SystemExit(2)
+        schema_source = argv[index + 1]
+        del argv[index : index + 2]
+    cli = build_cli(schema_source)
+    cli.main(args=argv, prog_name="current")
+
+
+if __name__ == "__main__":
+    main()