honcho-cli 0.1.0__tar.gz → 0.1.2__tar.gz

{honcho_cli-0.1.0 → honcho_cli-0.1.2}/.gitignore

@@ -193,3 +193,6 @@ metrics.jsonl
 AGENTS.md
 lancedb_data/
 grafana-data/
+
+# Claude Code addon stuff
+.omc

honcho_cli-0.1.2/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [0.1.2] - 2026-07-20
+
+### Added
+
+- Device-code OAuth login for managed Honcho servers. `honcho init` now offers browser-based login (RFC 8628 device authorization grant) when the host advertises the device grant in its OAuth authorization-server metadata; tokens are persisted to `~/.honcho/config.json` and auto-refreshed (#891)
+
+## [0.1.1] - 2026-06-15
+
+### Fixed
+
+- Declare `click` as an explicit dependency. The CLI imported `click` directly but relied on it being pulled in transitively, so installs without it on the path could fail at runtime (#787)
+
+## [0.1.0] - 2026-04-20
+
+### Added
+
+- Initial release of `honcho-cli` — a terminal for inspecting and managing a Honcho deployment (#424)
+- `workspace`, `peer`, `session`, `message`, `conclusion`, and `config` command groups for managing resources against any Honcho server
+- `init` onboarding flow that prompts for and persists connection settings, with flag/env-var pre-seeding for non-interactive use
+- Per-command flags, environment variables, and a config file for pointing the CLI at different servers (local, self-hosted, or hosted)
+- Rich terminal output and an agent-usage mode for scripting against the CLI
+- Documentation and an agent skill for the CLI (#589)

{honcho_cli-0.1.0 → honcho_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: honcho-cli
-Version: 0.1.0
+Version: 0.1.2
 Summary: A terminal for Honcho — memory that reasons.
 Project-URL: Homepage, https://github.com/plastic-labs/honcho
 Project-URL: Repository, https://github.com/plastic-labs/honcho
@@ -13,6 +13,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.11
+Requires-Dist: click>=8.0.0
 Requires-Dist: honcho-ai>=2.0.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: rich>=13.0.0
@@ -43,16 +44,6 @@ As a standalone tool (recommended):
 uv tool install honcho-cli
 ```
 
-As an extra on the Honcho SDK (if you want both the SDK and the CLI in one project):
-
-```bash
-uv add honcho-ai[cli]
-# or
-pip install honcho-ai[cli]
-```
-
-Either way, you'll get the `honcho` command on your PATH.
-
 ## Quick Start
 
 ```bash
@@ -166,6 +157,16 @@ Non-interactive onboarding:
 HONCHO_API_KEY=hch-v3-xxx honcho init --base-url https://api.honcho.dev
 ```
 
+## Agent skill
+
+`honcho-cli` ships with a skill that teaches agents the right commands and conventions for inspecting and debugging a Honcho deployment. Install it anywhere skills are accepted (Claude Code, other skill-aware agents):
+
+```bash
+npx skills add plastic-labs/honcho
+```
+
+The picker lists every skill for Honcho — select `honcho-cli` .
+
 ## Environment Variables
 
 All `HONCHO_*` env vars work at runtime — no config file required.

{honcho_cli-0.1.0 → honcho_cli-0.1.2}/README.md

@@ -19,16 +19,6 @@ As a standalone tool (recommended):
 uv tool install honcho-cli
 ```
 
-As an extra on the Honcho SDK (if you want both the SDK and the CLI in one project):
-
-```bash
-uv add honcho-ai[cli]
-# or
-pip install honcho-ai[cli]
-```
-
-Either way, you'll get the `honcho` command on your PATH.
-
 ## Quick Start
 
 ```bash
@@ -142,6 +132,16 @@ Non-interactive onboarding:
 HONCHO_API_KEY=hch-v3-xxx honcho init --base-url https://api.honcho.dev
 ```
 
+## Agent skill
+
+`honcho-cli` ships with a skill that teaches agents the right commands and conventions for inspecting and debugging a Honcho deployment. Install it anywhere skills are accepted (Claude Code, other skill-aware agents):
+
+```bash
+npx skills add plastic-labs/honcho
+```
+
+The picker lists every skill for Honcho — select `honcho-cli` .
+
 ## Environment Variables
 
 All `HONCHO_*` env vars work at runtime — no config file required.

{honcho_cli-0.1.0 → honcho_cli-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "honcho-cli"
-version = "0.1.0"
+version = "0.1.2"
 description = "A terminal for Honcho — memory that reasons."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -17,6 +17,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries",
 ]
 dependencies = [
+    "click>=8.0.0",
     "typer>=0.15.0",
     "honcho-ai>=2.0.0",
     "rich>=13.0.0",

honcho_cli-0.1.2/scripts/generate_cli_docs.py

@@ -0,0 +1,261 @@
+"""Generate ``docs/snippets/cli-commands.mdx`` from the Typer app.
+
+Walks the ``honcho`` Typer app and emits a Mintlify snippet using native
+Mintlify components: ``<AccordionGroup>`` / ``<Accordion>`` for subcommand
+grouping and ``<ParamField>`` for each argument and option. The output is a
+single snippet included by ``docs/v3/documentation/reference/cli.mdx``.
+
+Usage::
+
+    uv run --package honcho-cli python honcho-cli/scripts/generate_cli_docs.py
+
+    # Or as a drift check (non-zero exit if the committed snippet is stale):
+    uv run --package honcho-cli python honcho-cli/scripts/generate_cli_docs.py --check
+"""
+
+from __future__ import annotations
+
+import sys
+from argparse import ArgumentParser
+from pathlib import Path
+
+import click
+import typer.main
+
+from honcho_cli.main import app
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+OUTPUT = REPO_ROOT / "docs" / "snippets" / "cli-commands.mdx"
+
+HEADER = """{/*
+  GENERATED by honcho-cli/scripts/generate_cli_docs.py — do not edit.
+  Re-generate with: uv run --package honcho-cli python honcho-cli/scripts/generate_cli_docs.py
+  Source of truth: honcho-cli/src/honcho_cli/commands/
+*/}
+
+"""
+
+# Documented once in cli.mdx's Configuration table. Skip at the per-command
+# level so each Accordion only shows options specific to that subcommand.
+GLOBAL_OPTIONS: set[tuple[str, str]] = {
+    ("--workspace", "Override workspace ID"),
+    ("--peer", "Override peer ID"),
+    ("--session", "Override session ID"),
+    ("--json", "Force JSON output"),
+}
+
+
+def _escape_mdx(text: str) -> str:
+    """Escape MDX-sensitive characters in prose so Mintlify's parser doesn't
+    mistake ``{...}`` for a JSX expression or ``<x>`` for a JSX tag."""
+    return (
+        text.replace("\\", "\\\\")
+        .replace("{", "\\{")
+        .replace("}", "\\}")
+        .replace("<", "\\<")
+    )
+
+
+def _attr(value: str) -> str:
+    """Escape a string for use inside a JSX double-quoted attribute value."""
+    return value.replace("\\", "\\\\").replace('"', "'")
+
+
+def _long_opt(param: click.Option) -> str | None:
+    return next((o for o in param.opts if o.startswith("--")), None)
+
+
+def _short_opt(param: click.Option) -> str | None:
+    return next(
+        (o for o in param.opts if o.startswith("-") and not o.startswith("--")),
+        None,
+    )
+
+
+def _is_global(param: click.Parameter) -> bool:
+    if not isinstance(param, click.Option) or not param.help:
+        return False
+    return (_long_opt(param), param.help) in GLOBAL_OPTIONS
+
+
+def _param_type(param: click.Parameter) -> str:
+    if isinstance(param, click.Option) and param.is_flag:
+        return "boolean"
+    if isinstance(param.type, click.Choice):
+        return "string"
+    name = getattr(param.type, "name", "")
+    if name in ("integer", "int"):
+        return "number"
+    if name in ("float", "decimal"):
+        return "number"
+    if name == "boolean":
+        return "boolean"
+    return "string"
+
+
+def _param_path(param: click.Parameter) -> str:
+    if isinstance(param, click.Argument):
+        return param.name or ""
+    return _long_opt(param) or (param.opts[0] if param.opts else "")
+
+
+def _param_required(param: click.Parameter) -> bool:
+    if isinstance(param, click.Argument):
+        return param.required
+    if isinstance(param, click.Option):
+        return bool(param.required)
+    return False
+
+
+def _default_attr(param: click.Parameter) -> str | None:
+    default = param.default
+    if default is None or default is False or callable(default):
+        return None
+    if isinstance(default, (list, tuple)) and not default:
+        return None
+    if default is True:
+        return "true"
+    return _attr(str(default))
+
+
+def _ensure_period(text: str) -> str:
+    return text if text.endswith((".", "?", "!", ":")) else text + "."
+
+
+def _param_body(param: click.Parameter) -> str:
+    parts: list[str] = []
+    if isinstance(param, click.Option):
+        if param.help:
+            parts.append(_ensure_period(_escape_mdx(param.help.strip())))
+        short = _short_opt(param)
+        if short:
+            parts.append(f"Short alias: `{short}`.")
+        if param.secondary_opts:
+            neg = " / ".join(f"`{o}`" for o in param.secondary_opts)
+            parts.append(f"Negate with {neg}.")
+        if isinstance(param.type, click.Choice):
+            choices = ", ".join(f"`{c}`" for c in param.type.choices)
+            parts.append(f"One of: {choices}.")
+    return " ".join(parts)
+
+
+def _render_param(param: click.Parameter) -> list[str]:
+    props = [
+        f'path="{_attr(_param_path(param))}"',
+        f'type="{_param_type(param)}"',
+    ]
+    if _param_required(param):
+        props.append("required")
+    default_attr = _default_attr(param)
+    if default_attr is not None:
+        props.append(f'default="{default_attr}"')
+    body = _param_body(param).strip()
+    open_tag = f"<ParamField {' '.join(props)}>"
+    if body:
+        return [open_tag, f"  {body}", "</ParamField>"]
+    return [open_tag.replace(">", " />")]
+
+
+def _params_of(
+    cmd: click.Command, *, strip_globals: bool
+) -> list[click.Parameter]:
+    args = [p for p in cmd.params if isinstance(p, click.Argument)]
+    opts = [
+        p
+        for p in cmd.params
+        if isinstance(p, click.Option)
+        and not p.hidden
+        and not (strip_globals and _is_global(p))
+    ]
+    return args + opts
+
+
+def _invocation_line(cmd: click.Command, path: list[str]) -> str:
+    args = [p for p in cmd.params if isinstance(p, click.Argument)]
+    parts = [" ".join(path)]
+    for a in args:
+        placeholder = f"<{a.name}>"
+        if not a.required:
+            placeholder = f"[{placeholder}]"
+        parts.append(placeholder)
+    return " ".join(parts)
+
+
+def _render_accordion(cmd: click.Command, path: list[str]) -> list[str]:
+    lines = [f'<Accordion title="{_attr(path[-1])}">']
+    if cmd.help:
+        lines.append(_escape_mdx(cmd.help.strip()))
+        lines.append("")
+    lines.append("```bash")
+    lines.append(_invocation_line(cmd, path))
+    lines.append("```")
+    lines.append("")
+    for p in _params_of(cmd, strip_globals=True):
+        lines.extend(_render_param(p))
+    lines.append("</Accordion>")
+    return lines
+
+
+def _render_top(cmd: click.Command, path: list[str]) -> list[str]:
+    lines = [f"## {' '.join(path)}", ""]
+    if cmd.help:
+        lines.append(_escape_mdx(cmd.help.strip()))
+        lines.append("")
+
+    if isinstance(cmd, click.Group) and cmd.commands:
+        lines.append("<AccordionGroup>")
+        for sub_name in sorted(cmd.commands):
+            lines.extend(
+                _render_accordion(cmd.commands[sub_name], path + [sub_name])
+            )
+        lines.append("</AccordionGroup>")
+        lines.append("")
+        return lines
+
+    lines.append("```bash")
+    lines.append(_invocation_line(cmd, path))
+    lines.append("```")
+    lines.append("")
+    for p in _params_of(cmd, strip_globals=True):
+        lines.extend(_render_param(p))
+    lines.append("")
+    return lines
+
+
+def build() -> str:
+    root: click.Command = typer.main.get_command(app)
+    if not isinstance(root, click.Group):
+        raise SystemExit("Expected root command to be a Group")
+
+    body: list[str] = []
+    for name in sorted(root.commands):
+        body.extend(_render_top(root.commands[name], ["honcho", name]))
+    return HEADER + "\n".join(body) + "\n"
+
+
+def main() -> int:
+    parser = ArgumentParser()
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Exit non-zero if the committed snippet differs from generated output.",
+    )
+    ns = parser.parse_args()
+    generated = build()
+    if ns.check:
+        current = OUTPUT.read_text() if OUTPUT.exists() else ""
+        if current != generated:
+            print(
+                f"::error::{OUTPUT} is stale. Re-run without --check to regenerate.",
+                file=sys.stderr,
+            )
+            return 1
+        return 0
+    OUTPUT.parent.mkdir(parents=True, exist_ok=True)
+    OUTPUT.write_text(generated)
+    print(f"Wrote {OUTPUT}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{honcho_cli-0.1.0 → honcho_cli-0.1.2}/src/honcho_cli/__init__.py

@@ -1,3 +1,3 @@
 """Honcho CLI — a terminal for Honcho."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"

{honcho_cli-0.1.0 → honcho_cli-0.1.2}/src/honcho_cli/commands/setup.py

@@ -7,6 +7,8 @@
 from __future__ import annotations
 
 import json
+import time
+import webbrowser
 
 import typer
 from honcho import (
@@ -19,13 +21,14 @@ from honcho import (
 from rich.console import Console
 from rich.panel import Panel
 
-from honcho_cli import __version__
+from honcho_cli import __version__, oauth
 from honcho_cli.branding import BANNER, BRAND, ICON_FAIL, ICON_OK, ICON_RUN
-from honcho_cli.common import get_resolved_config
+from honcho_cli.common import get_resolved_config, maybe_refresh_token
 from honcho_cli.config import (
     CONFIG_FILE,
     DEFAULT_BASE_URL,
     CLIConfig,
+    OAuthTokens,
 )
 from honcho_cli.output import print_error, print_result, set_json_mode, use_json
 
@@ -117,21 +120,142 @@ def init(
         _console.print()
         _console.print()
 
+    # Non-interactive (JSON/piped) or an explicit --api-key: manual-key path.
+    # Device login needs a human at a browser, so it's TTY-only.
+    if use_json() or api_key:
+        _init_manual_key(key_val, url_val, file_key, file_url)
+    else:
+        _init_interactive(key_val, url_val, file_url)
+
+
+def _init_manual_key(key_val: str, url_val: str, file_key: str, file_url: str) -> None:
+    """Non-interactive path: confirm/save apiKey + URL, no device login."""
     final_key = _prompt_api_key(key_val)
     final_url = _prompt_url(url_val)
-
-    # Persist if anything changed or if the value came from env/flag.
     if final_key != file_key or final_url != file_url:
         CLIConfig(base_url=final_url, api_key=final_key).save()
         if not use_json():
             _console.print(f"  {ICON_OK} [dim]Saved to {CONFIG_FILE}[/dim]")
-
     _check_connection(final_url, final_key)
-
     if use_json():
         print_result({"apiKey": _redact(final_key), "baseUrl": final_url})
 
 
+def _init_interactive(key_val: str, url_val: str, file_url: str) -> None:
+    """Interactive path: URL first (device flow needs the host), then auth method."""
+    final_url = _prompt_url(url_val)
+    existing = CLIConfig.load()
+    has_creds = bool(key_val) or bool(existing.oauth and existing.oauth.access_token)
+    # only offer browser login if the host advertises the device grant (managed)
+    device_available = oauth.supports_device_login(final_url)
+    method = _prompt_auth_method(has_creds, device_available)
+
+    if method == "keep":
+        if final_url != file_url:
+            existing.base_url = final_url
+            existing.save()
+            _console.print(f"  {ICON_OK} [dim]Saved to {CONFIG_FILE}[/dim]")
+        # refresh an expired token so "keep" behaves like every live command;
+        # a failed refresh surfaces as the connectivity check below, not an abort
+        try:
+            maybe_refresh_token(existing)
+        except typer.Exit:
+            pass
+        _check_connection(final_url, existing.resolved_api_key())
+        return
+
+    if method == "device":
+        tokens = _device_login(final_url)
+        CLIConfig(base_url=final_url, oauth=tokens).save()
+        _console.print(f"  {ICON_OK} [dim]Saved to {CONFIG_FILE}[/dim]")
+        _check_connection(final_url, tokens.access_token)
+        return
+
+    # paste a key
+    final_key = _prompt_api_key("")
+    CLIConfig(base_url=final_url, api_key=final_key).save()
+    _console.print(f"  {ICON_OK} [dim]Saved to {CONFIG_FILE}[/dim]")
+    _check_connection(final_url, final_key)
+
+
+def _prompt_auth_method(has_creds: bool, device_available: bool) -> str:
+    """Ask how to authenticate. Returns ``device`` / ``key`` / ``keep``.
+
+    ``device`` is only offered when the host advertises the device grant; when
+    it doesn't, pasting a key is the only login path.
+    """
+    _console.print("  [dim]How do you want to authenticate?[/dim]")
+    options: list[str] = []
+    if device_available:
+        options.append("device")
+        _console.print(f"  [dim]({len(options)})[/dim] Log in with your browser (device code)")
+    options.append("key")
+    _console.print(f"  [dim]({len(options)})[/dim] Paste an API key")
+    if has_creds:
+        options.append("keep")
+        _console.print(f"  [dim]({len(options)})[/dim] Keep current credentials")
+    # default to keeping existing creds so a returning user pressing Enter doesn't
+    # get dropped into an unwanted browser login that overwrites them
+    default = str(options.index("keep") + 1) if "keep" in options else "1"
+    choice = typer.prompt("  Choice", default=default, show_default=True, prompt_suffix=": ").strip()
+    try:
+        idx = int(choice)
+    except ValueError:
+        return options[0]
+    # explicit 1..len bounds — bare `options[idx - 1]` would let "0"/negatives
+    # wrap to the tail of the list via Python's negative indexing
+    if 1 <= idx <= len(options):
+        return options[idx - 1]
+    return options[0]
+
+
+def _device_login(base_url: str) -> OAuthTokens:
+    """Run the device-authorization flow and return the minted tokens.
+
+    Prints the user code + verification URL, opens the browser best-effort, and
+    blocks on the poll loop until the user approves. Exits non-zero on denial,
+    expiry, or interrupt.
+    """
+    endpoints = oauth.resolve_endpoints(base_url)
+    try:
+        device = oauth.request_device_code(endpoints)
+    except oauth.OAuthFlowError as e:
+        _console.print(f"  {ICON_FAIL} [red]Could not start device login[/red]: {e}")
+        raise typer.Exit(1)
+
+    _console.print()
+    _console.print(f"  Enter this code to authorize: [bold {BRAND}]{device.user_code}[/bold {BRAND}]")
+    _console.print(f"  [dim]at[/dim] {device.verification_uri}")
+    _console.print()
+    try:
+        webbrowser.open(device.verification_uri_complete)
+    except Exception:
+        pass  # headless is expected — the URL is printed above
+
+    try:
+        with _console.status("Waiting for approval…", spinner="dots"):
+            tokens = oauth.poll_for_token(endpoints, device)
+    except oauth.AccessDenied:
+        _console.print(f"  {ICON_FAIL} [red]Authorization denied[/red]")
+        raise typer.Exit(1)
+    except (oauth.DeviceCodeExpired, oauth.AuthorizationTimeout):
+        _console.print(f"  {ICON_FAIL} [red]Code expired[/red] — run `honcho init` to try again")
+        raise typer.Exit(1)
+    except oauth.OAuthFlowError as e:
+        _console.print(f"  {ICON_FAIL} [red]Login failed[/red]: {e}")
+        raise typer.Exit(1)
+    except KeyboardInterrupt:
+        _console.print(f"  {ICON_FAIL} [red]Cancelled[/red]")
+        raise typer.Exit(1)
+
+    return OAuthTokens.from_response(
+        tokens,
+        client_id=endpoints.client_id,
+        scope_fallback=endpoints.scope,
+        host=base_url,
+    )
+
+
 def _prompt_api_key(value: str) -> str:
     """Prompt for API key.
 
@@ -206,6 +330,21 @@ def _check_connection(base_url: str, api_key: str) -> None:
 # --------------------------------------------------------------------------- #
 # honcho doctor
 
+def _auth_mode_detail(config: CLIConfig) -> str:
+    """Human summary of which credential the CLI will use."""
+    tokens = config.usable_oauth()
+    if tokens is not None:
+        if tokens.access_valid():
+            secs = max(int(tokens.access_expires_at - time.time()), 0)
+            return f"OAuth device token (expires in {secs // 60}m)"
+        if config.api_key:
+            return "API key (OAuth token expired)"
+        return "OAuth device token (expired — will refresh)"
+    if config.api_key:
+        return "API key"
+    return "missing — run `honcho init`"
+
+
 def doctor(
     json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
 ) -> None:
@@ -230,23 +369,30 @@ def doctor(
         _console.print(f"\n[bold {BRAND}]Honcho Doctor[/bold {BRAND}]\n")
 
     config = get_resolved_config()
+    # Refresh an expired OAuth token if we can; a failure surfaces as a failed
+    # connectivity check below rather than aborting the diagnostic.
+    try:
+        maybe_refresh_token(config)
+    except typer.Exit:
+        pass
+    key = config.resolved_api_key()
+
     _add("Config file", CONFIG_FILE.exists(),
          str(CONFIG_FILE) if CONFIG_FILE.exists() else f"{CONFIG_FILE} not found")
-    _add("API key configured", bool(config.api_key),
-         "set" if config.api_key else "missing — run `honcho init`")
+    _add("Credentials configured", bool(key), _auth_mode_detail(config))
 
-    if config.base_url and config.api_key:
-        _add("API connectivity", *_test_connection(config.base_url, config.api_key))
+    if config.base_url and key:
+        _add("API connectivity", *_test_connection(config.base_url, key))
     else:
-        _add("API connectivity", False, "skipped — no base_url or api_key")
+        _add("API connectivity", False, "skipped — no base_url or credentials")
 
     # Workspace / peer / queue run only when scoped via -w / -p.
     ws_ok, client = False, None
-    if config.workspace_id and config.api_key:
+    if config.workspace_id and key:
         try:
 
 
-            client = Honcho(base_url=config.base_url, api_key=config.api_key, workspace_id=config.workspace_id)
+            client = Honcho(base_url=config.base_url, api_key=key, workspace_id=config.workspace_id)
             client.get_configuration()
             ws_ok = True
             _add("Workspace reachable", True, config.workspace_id)
@@ -280,7 +426,7 @@ def doctor(
         _console.print(f"\n  [{color}]{passed}/{total}[/{color}] checks passed{hint}\n")
 
     # Config file + API connectivity are hard requirements.
-    critical = {"Config file", "API key configured", "API connectivity"}
+    critical = {"Config file", "Credentials configured", "API connectivity"}
     if config.workspace_id:
         critical.add("Workspace reachable")
     if any(not c["ok"] for c in checks if c["check"] in critical):