gravity-cli 0.1.0__py3-none-any.whl

gravity_cli/commands/init.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import re
+import shutil
+from pathlib import Path
+
+import typer
+from gravity_schema import AGENT_NAME_RE
+from rich import print as rprint
+
+TEMPLATES_DIR = Path(__file__).parent.parent / "templates"
+TEMPLATE_NAMES = ["minimal", "structured", "deepagent", "chat"]
+
+
+def _slugify(raw: str) -> str:
+    """A directory name is not necessarily a valid agent name."""
+    slug = re.sub(r"[^a-z0-9]+", "-", raw.lower()).strip("-")
+    return re.sub(r"-{2,}", "-", slug)
+
+
+def init_command(
+    name: str = typer.Argument(
+        None, help="Name of the agent, and of the folder created"
+    ),
+    template: str = typer.Option(
+        "minimal", "--template", help=f"Starting point: {', '.join(TEMPLATE_NAMES)}"
+    ),
+    here: bool = typer.Option(
+        False, "--here", help="Add only a manifest.yaml to the current folder, for an existing project"
+    ),
+):
+    """Scaffold a working agent: manifest, pinned deps and a src/agent.py that runs."""
+    if template not in TEMPLATE_NAMES:
+        rprint(f"[red]unknown template {template!r}[/red] — pick one of: {', '.join(TEMPLATE_NAMES)}")
+        raise typer.Exit(1)
+
+    # --here takes its name from the directory.
+    if not name:
+        if not here:
+            rprint("[red]✖[/red] `gravity init` needs a name, e.g. `gravity init my-agent`.")
+            rprint("  [dim]or `gravity init --here` inside an existing agent repo[/dim]")
+            raise typer.Exit(1)
+        name = _slugify(Path.cwd().name)
+
+    if not AGENT_NAME_RE.match(name):
+        rprint(f"[red]✖[/red] {name!r} is not a valid agent name.")
+        rprint("  [dim]lowercase letters, digits and single hyphens, e.g. 'inbox-triager'[/dim]")
+        raise typer.Exit(1)
+
+    src_dir = TEMPLATES_DIR / template
+    manifest_text = (src_dir / "manifest.yaml").read_text(encoding="utf-8").replace("{{name}}", name)
+
+    if here:
+        dest = Path.cwd()
+        manifest_dest = dest / "manifest.yaml"
+        if manifest_dest.exists():
+            rprint(f"[red]manifest.yaml already exists in {dest}[/red] — not overwriting.")
+            raise typer.Exit(1)
+        manifest_dest.write_text(manifest_text, encoding="utf-8")
+        rprint(f"[green]wrote {manifest_dest}[/green]")
+        rprint(
+            "edit permissions.tools and runtime.entrypoint to match your existing agent, "
+            "then `gravity validate`."
+        )
+        return
+
+    dest = Path.cwd() / name
+    if dest.exists():
+        rprint(f"[red]{dest} already exists[/red]")
+        raise typer.Exit(1)
+
+    shutil.copytree(src_dir, dest)
+    (dest / "manifest.yaml").write_text(manifest_text, encoding="utf-8")
+
+    rprint(f"[green]created {dest}[/green] ({template} template)")
+    rprint(f"\n  cd {name}")
+    rprint("  uv venv && uv pip install -r requirements.txt")
+    rprint('  gravity run --input query="hello"')

gravity_cli/commands/login.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import time
+import webbrowser
+
+import typer
+from rich import print as rprint
+
+from .. import api, config
+
+
+def login_command():
+    """Log in with a browser device code; the token goes in the OS keychain."""
+    start = api.device_start()
+    device_code = start["deviceCode"]
+    user_code = start["userCode"]
+    verification_url = start["verificationUrl"]
+    interval = start.get("interval", 3)
+    expires_in = start.get("expiresIn", 600)
+
+    rprint(f"opening {verification_url} in your browser…")
+    rprint(f"[dim]if it doesn't open, visit the link above and enter code: [bold]{user_code}[/bold][/dim]")
+    webbrowser.open(verification_url)
+    rprint("[dim]waiting for approval…[/dim]")
+
+    deadline = time.time() + expires_in
+    while time.time() < deadline:
+        time.sleep(interval)
+        result = api.device_poll(device_code)
+
+        if result["status"] == "approved":
+            session_data = result["session"]
+            config.save_session(
+                config.Session(
+                    access_token=session_data["accessToken"],
+                    refresh_token=session_data["refreshToken"],
+                )
+            )
+            rprint("[green]✓ logged in[/green]")
+            return
+
+    rprint("[red]✖[/red] timed out waiting for approval — run `gravity login` again.")
+    raise typer.Exit(1)
+
+
+def whoami_command():
+    """If you forget who you are."""
+    me = api.get("/api/cli/me")
+    me = me if isinstance(me, dict) else {}
+    role = me.get("userType", "")
+    # Only the dev token (GRAVITY_API_TOKEN) is a user without an email.
+    who = me.get("email") or f"{me.get('id', '')} (dev token)"
+    rprint(f"{who}{f'  [dim]· {role}[/dim]' if role else ''}")
+
+
+def logout_command():
+    config.clear_session()
+    rprint("[green]✓ logged out[/green]")

gravity_cli/commands/push.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from pathlib import Path
+
+import typer
+from rich import print as rprint
+
+from .. import api
+from ..manifest import ManifestValidationError, load_manifest, render_issues
+from ..project import source_digest
+from .build import build_paths
+
+
+def push_command(
+    path: Path = typer.Argument(Path("."), help="Agent folder"),
+):
+    """Upload what `gravity build` made; refuses if there's no build or it's stale."""
+    project_dir = path.resolve()
+    zip_path, meta_path = build_paths(project_dir)
+
+    if not zip_path.is_file() or not meta_path.is_file():
+        rprint("[red]✖[/red] no build found — run `gravity build` first.")
+        raise typer.Exit(1)
+
+    try:
+        meta = json.loads(meta_path.read_text())
+    except (json.JSONDecodeError, OSError) as e:
+        rprint(f"[red]✖[/red] {meta_path.name} is unreadable — re-run `gravity build`.")
+        raise typer.Exit(1) from e
+
+    zip_bytes = zip_path.read_bytes()
+    zip_sha256 = hashlib.sha256(zip_bytes).hexdigest()
+    if zip_sha256 != meta.get("zip_sha256"):
+        rprint(
+            f"[red]✖[/red] {zip_path.name} doesn't match {meta_path.name} — re-run `gravity build`."
+        )
+        raise typer.Exit(1)
+
+    if source_digest(project_dir) != meta.get("source_sha256"):
+        rprint(
+            "[red]✖[/red] build is stale — src/, manifest or requirements changed since "
+            f"`gravity build` ran ({meta.get('built_at', 'unknown time')}). re-run `gravity build`."
+        )
+        raise typer.Exit(1)
+
+    try:
+        manifest = load_manifest(project_dir / "manifest.yaml")
+    except ManifestValidationError as e:
+        render_issues(e)
+        raise typer.Exit(1) from e
+
+    rprint(f"[dim]pushing {zip_path.name} · {len(zip_bytes)} bytes · sha256:{zip_sha256[:12]}…[/dim]")
+
+    result = api.push_agent(manifest.model_dump(mode="json"), zip_bytes, zip_sha256)
+
+    rprint(
+        f"[green]✓ {result['name']}@{result['version']}[/green] "
+        f"— status: {result['status']}"
+    )
+    if result.get("message"):
+        rprint(f"[dim]{result['message']}[/dim]")
+
+    if result["status"] in BUILDING:
+        _wait_for_build(result["name"], result["version"], result["status"])
+
+
+BUILDING = ("queued", "building")
+POLL_SECONDS = 5
+# Only stops the CLI waiting forever; the build machine gives up well before.
+MAX_WAIT_SECONDS = 45 * 60
+
+
+def _wait_for_build(name: str, version: str, status: str) -> None:
+    """Poll the version until the build machine marks it ready or failed."""
+    waited = 0
+    v: dict = {}
+    try:
+        while status in BUILDING and waited < MAX_WAIT_SECONDS:
+            time.sleep(POLL_SECONDS)
+            waited += POLL_SECONDS
+            v = api.get(f"/api/cli/agents/{name}/versions/{version}")
+            if v["status"] != status:
+                rprint(f"[dim]… {v['status']}[/dim]")
+            status = v["status"]
+    except KeyboardInterrupt:
+        rprint(f"[dim]stopped waiting; the build carries on. `gravity agents` shows {name}'s status.[/dim]")
+        return
+
+    if status == "ready":
+        rprint(f"[green]✓ {name}@{version} is ready[/green]")
+    elif status == "failed":
+        rprint(f"[red]✖ {name}@{version} failed:[/red] {v.get('status_reason') or 'no reason given'}")
+        raise typer.Exit(1)
+    else:
+        rprint(f"[dim]still {status} after {MAX_WAIT_SECONDS // 60} min; `gravity agents` shows its status.[/dim]")

gravity_cli/commands/run.py

@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import httpx
+import typer
+from rich import print as rprint
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Confirm
+from rich.text import Text
+
+from .. import project
+from ..manifest import ManifestValidationError, load_manifest, render_issues
+from ..timeline import EVENT_PREFIX, Timeline
+
+RUNNER_SCRIPT = Path(__file__).parent.parent / "_runner_script.py"
+# The builder's own tokens: never handed to agent or LLM-written code.
+BUILDER_TOKENS = ("GRAVITY_DEV_TOKEN", "GRAVITY_API_TOKEN")
+
+
+def gateway_urls() -> tuple[str, str]:
+    """(MCP url, host base). Defaults to `gravity-gateway serve`'s own port."""
+    url = os.environ.get("GRAVITY_GATEWAY_URL") or "http://127.0.0.1:8000/mcp"
+    return url, url.rstrip("/").removesuffix("/mcp")
+
+
+def _mint_run_token(gateway_base: str, tools: list[str], approvals: list[str] = ()) -> dict:
+    """Dev token -> a run token scoped to the manifest's tools, as a hosted run gets."""
+    dev_token = os.environ.get("GRAVITY_DEV_TOKEN")
+    if not dev_token:
+        rprint("[red]✖[/red] missing: GRAVITY_DEV_TOKEN")
+        rprint(
+            "[dim]set it once in ~/.gravity/.env (loaded automatically, no export needed). "
+            "A local `gravity-gateway serve` prints one at startup.[/dim]"
+        )
+        raise typer.Exit(1)
+    try:
+        resp = httpx.post(
+            f"{gateway_base}/runs",
+            json={"tools": tools, "approvals": list(approvals)},
+            headers={"Authorization": f"Bearer {dev_token}"},
+            timeout=15,
+        )
+    except httpx.HTTPError as e:
+        rprint(f"[red]✖[/red] can't reach the gateway at {gateway_base}: {e}")
+        rprint("[dim]start one with `gravity-gateway serve`, or set GRAVITY_GATEWAY_URL.[/dim]")
+        raise typer.Exit(1) from e
+    if resp.status_code != 201:
+        try:
+            err = resp.json()["error"]
+            detail = f"{err['code']}: {err['message']}"
+        except (ValueError, KeyError, TypeError):
+            detail = resp.text
+        rprint(f"[red]✖[/red] the gateway refused this run — {detail}")
+        raise typer.Exit(1)
+    return resp.json()  # token, run_id, ...
+
+
+def _kill_tree(proc: subprocess.Popen) -> None:
+    """Kill the agent and its children: on Windows a venv's python.exe is a launcher."""
+    if os.name == "nt":
+        subprocess.run(["taskkill", "/T", "/F", "/PID", str(proc.pid)], capture_output=True, check=False)
+    else:
+        proc.kill()
+    proc.wait()
+
+
+def _recipients(arguments: dict) -> list[str]:
+    return [t for t in [arguments.get("recipient_email"), *(arguments.get("extra_recipients") or [])] if t]
+
+
+def _summary(arguments: dict) -> str:
+    """One line on what a held call would do."""
+    to = _recipients(arguments)
+    if to:
+        subject = arguments.get("subject")
+        return f"→ {', '.join(to)}" + (f' · "{subject}"' if subject else "")
+    return json.dumps(arguments, default=str)[:80]
+
+
+def _ask_approval(live, timeline: Timeline, ev: dict, gateway_base: str, run_id: str | None) -> None:
+    """Find the held call, show what it would do, send the builder's answer."""
+    headers = {"Authorization": f"Bearer {os.environ['GRAVITY_DEV_TOKEN']}"}
+    name = timeline._name(ev["tool"])
+    pending = None
+    for _ in range(60):  # the call reaches the gateway a moment after it starts
+        try:
+            held = httpx.get(f"{gateway_base}/approvals", params={"run": run_id}, headers=headers, timeout=5).json()
+        except (httpx.HTTPError, ValueError):
+            held = []
+        pending = next((a for a in held if a.get("tool") == name), None)
+        if pending:
+            break
+        time.sleep(0.25)
+    if pending is None:
+        return  # the call finished or failed on its own; its row will say how
+
+    args = pending.get("arguments") or {}
+    timeline.awaiting(ev.get("id"), _summary(args))
+    live.refresh()
+    live.stop()
+    timeline.console.line()  # the live view ends mid-line
+    to = _recipients(args)
+    lines = [f"[bold]{name}[/bold] wants to run, and this agent's manifest requires approval for it.", ""]
+    if to:
+        body = str(args.get("body") or "")
+        lines.append(f"to       {', '.join(to)}")
+        lines += [f"subject  {args['subject']}"] if args.get("subject") else []
+        lines += [f"body     {body[:300]}{'…' if len(body) > 300 else ''}"] if body else []
+    else:
+        lines.append(json.dumps(args, indent=2, default=str)[:600])
+    details = "\n".join(lines)
+    timeline.console.print(Panel(details, title="[yellow]approval needed", border_style="yellow", expand=False))
+    interrupted = False
+    unattended = os.environ.get("GRAVITY_UNATTENDED") == "1"
+    if sys.stdin.isatty() and not unattended:
+        try:
+            ok = Confirm.ask("  Approve?", default=False, console=timeline.console)
+        except (EOFError, KeyboardInterrupt):
+            # No answer is a no; Ctrl+C ends the run only after the gateway is told.
+            ok, interrupted = False, True
+            timeline.console.print("\n  [dim]no answer — not approved[/dim]")
+    else:
+        ok = False
+        reason = "scheduled run, nobody to ask" if unattended else "no terminal to ask in"
+        timeline.console.print(f"  [dim]{reason} — not approved. Run it interactively to approve.[/dim]")
+    try:
+        httpx.post(
+            f"{gateway_base}/approvals/{pending['id']}",
+            json={"decision": "approve" if ok else "reject"},
+            headers=headers,
+            timeout=10,
+        )
+    except httpx.HTTPError as e:
+        timeline.console.print(f"  [red]✖[/red] couldn't send the decision: {e} — the gateway will time it out")
+    if interrupted:
+        raise KeyboardInterrupt
+    if ok:
+        timeline.approved(ev.get("id"))
+    timeline.continue_below(ev.get("id"))
+    live.start()
+
+
+def run_command(
+    path: Path = typer.Argument(Path("."), help="Agent folder"),
+    input: list[str] = typer.Option(
+        [], "--input", help="An input as key=value, repeatable. key=@file.txt reads the value from a file"
+    ),
+    llm_url: str | None = typer.Option(
+        None, "--llm-url", help="Model endpoint to use instead of GRAVITY_LLM_URL"
+    ),
+    reply: str | None = typer.Option(
+        None, "--reply", help='Continue the last conversation of a chat agent, e.g. --reply "make it shorter"'
+    ),
+):
+    """Run your agent locally through the gateway. Needs GRAVITY_DEV_TOKEN in ~/.gravity/.env."""
+    project_dir = path.resolve()
+    try:
+        manifest = load_manifest(project_dir / "manifest.yaml")
+    except ManifestValidationError as e:
+        render_issues(e)
+        raise typer.Exit(1) from e
+
+    inputs = {}
+    for item in input:
+        if "=" not in item:
+            rprint(f"[red]✖[/red] --input {item!r} must be key=value")
+            raise typer.Exit(1)
+        k, v = item.split("=", 1)
+        if v.startswith("@"):
+            try:
+                v = Path(v[1:]).read_text(encoding="utf-8")
+            except OSError as e:
+                rprint(f"[red]✖[/red] --input {k}: can't read {v[1:]}: {e.strerror}")
+                raise typer.Exit(1) from e
+        inputs[k] = v
+
+    gateway_url, gateway_base = gateway_urls()
+    # A chat agent's last transcript, kept locally the way the platform keeps a thread.
+    thread_file = project_dir / ".gravity" / "thread.json"
+    history = None
+    if reply is not None:
+        if not thread_file.is_file():
+            rprint("[red]✖[/red] nothing to reply to: run it once first (only agents whose state has `messages` keep a thread)")
+            raise typer.Exit(1)
+        thread = json.loads(thread_file.read_text(encoding="utf-8"))
+        inputs = {**thread["inputs"], **inputs}
+        history = thread["messages"] + [{"role": "user", "content": reply}]
+
+    # Manifest defaults fill unset inputs, slot picks included.
+    inputs = {**manifest.default_inputs(), **inputs}
+    missing = [i.name for i in manifest.inputs if i.required and inputs.get(i.name) in (None, "")]
+    if missing:
+        rprint(f"[red]✖[/red] missing required input(s): {', '.join(missing)} — pass --input {missing[0]}=...")
+        raise typer.Exit(1)
+    try:
+        tools = manifest.tools_for(inputs)
+    except ValueError as e:
+        rprint(f"[red]✖[/red] --input {e}")
+        raise typer.Exit(1) from e
+    gated = [t for t in manifest.approvals.required_for if t in tools]
+    minted = _mint_run_token(gateway_base, tools, gated)
+    run_token, run_id = minted["token"], minted.get("run_id")
+
+    env = {
+        # The agent gets the run token only, never BUILDER_TOKENS.
+        **{k: v for k, v in os.environ.items() if k not in BUILDER_TOKENS},
+        "GRAVITY_GATEWAY_URL": gateway_url,
+        "GRAVITY_RUN_TOKEN": run_token,
+        # Models share the tool gateway's host: .../mcp -> .../v1.
+        "GRAVITY_LLM_URL": llm_url or os.environ.get("GRAVITY_LLM_URL") or f"{gateway_base}/v1",
+    }
+
+    # Memory across runs (manifest `state`), kept locally as the platform keeps it.
+    memory_file = project_dir / ".gravity" / "memory.json"
+    payload = {"inputs": inputs, **({"messages": history} if history else {})}
+    if manifest.state is not None:
+        payload["memory"] = json.loads(memory_file.read_text(encoding="utf-8")) if memory_file.is_file() else {}
+
+    # Through a file, not argv: a pasted dataset overflows Windows' 32 KB command line.
+    payload_file = project_dir / ".gravity" / "payload.json"
+    payload_file.parent.mkdir(exist_ok=True)
+    payload_file.write_text(json.dumps(payload), encoding="utf-8")
+
+    entry_file, entry_object = manifest.entrypoint_parts()
+    python = project.find_python(project_dir)
+
+    env["PYTHONUTF8"] = "1"  # the runner's events carry non-ASCII text on Windows too
+    timeline = Timeline(
+        Console(),
+        agent=f"{manifest.name}@{manifest.version}",
+        run_token=run_token,
+        tools=tools,
+    )
+    proc = subprocess.Popen(
+        [python, str(RUNNER_SCRIPT), entry_file, entry_object, str(payload_file)],
+        cwd=project_dir,
+        env=env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    try:
+        with timeline.live() as live:
+            for line in proc.stdout:
+                line = line.rstrip("\n")
+                if line.startswith(EVENT_PREFIX):
+                    ev = json.loads(line[len(EVENT_PREFIX):])
+                    timeline.handle(ev)
+                    if ev.get("type") == "tool.started" and timeline._name(ev["tool"]) in gated:
+                        _ask_approval(live, timeline, ev, gateway_base, run_id)
+                elif line.strip():
+                    # The agent's own output, dimmed under the timeline.
+                    live.console.print(Text(line, style="dim"))
+    except BaseException:
+        # Leaving early: the agent must not carry on unobserved.
+        _kill_tree(proc)
+        raise
+    proc.wait()
+    outcome = timeline.outcome or {}
+    if outcome.get("messages"):
+        thread_file.parent.mkdir(exist_ok=True)
+        thread_file.write_text(json.dumps({"inputs": inputs, "messages": outcome["messages"]}), encoding="utf-8")
+    if manifest.state is not None and outcome.get("type") == "run.finished" and outcome.get("memory") is not None:
+        blob = json.dumps(outcome["memory"])
+        if len(blob.encode("utf-8")) > manifest.state.max_kb * 1024:
+            # Over the cap: keep the old memory rather than a truncated one.
+            rprint(f"[yellow]⚠[/yellow]  memory is over state.max_kb ({manifest.state.max_kb} KB) — not saved")
+        else:
+            memory_file.parent.mkdir(exist_ok=True)
+            memory_file.write_text(blob, encoding="utf-8")
+    code = timeline.finish()
+    raise typer.Exit(code or proc.returncode)

gravity_cli/commands/runs.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import typer
+from rich import print as rprint
+from rich.console import Console
+from rich.table import Table
+
+from .. import api
+
+console = Console()
+
+
+def agents_command():
+    """Your agents in the marketplace, with review status."""
+    agents = api.get("/api/cli/agents")
+    table = Table()
+    for col in ("name", "version", "status", "updated_at"):
+        table.add_column(col)
+    for a in agents:
+        table.add_row(a.get("name", ""), str(a.get("version", "")), a.get("status", ""), a.get("updated_at", ""))
+    console.print(table)
+
+
+def runs_command(
+    agent_name: str = typer.Argument(..., help="Name of the agent"),
+):
+    """Recent runs with status and cost."""
+    runs = api.get(f"/api/cli/agents/{agent_name}/runs")
+    if not runs:
+        rprint(f"[dim]no runs yet for {agent_name}.[/dim]")
+        return
+    table = Table()
+    for col in ("id", "status", "started_at", "cost"):
+        table.add_column(col)
+    for r in runs:
+        table.add_row(r.get("id", ""), r.get("status", ""), r.get("started_at", ""), str(r.get("cost", "")))
+    console.print(table)
+
+
+def logs_command(
+    run_id: str = typer.Argument(..., help="Run id, as shown by gravity runs"),
+):
+    """The full timeline + your own stdout for one run."""
+    logs = api.get(f"/api/cli/runs/{run_id}/logs")
+    if logs.get("message"):
+        rprint(f"[dim]{logs['message']}[/dim]")
+        return
+    for line in logs.get("lines", []):
+        rprint(line)

gravity_cli/commands/schedule.py

@@ -0,0 +1,74 @@
+"""`gravity schedule`: each tick is an ordinary `gravity run` with nobody at the terminal,
+so gated calls are not approved."""
+
+from __future__ import annotations
+
+import os
+import time
+from datetime import datetime
+from pathlib import Path
+
+import typer
+from gravity_schema.cron import next_run
+from gravity_schema.manifest import ScheduleSpec
+from rich import print as rprint
+
+from ..manifest import ManifestValidationError, load_manifest, render_issues
+from .run import run_command
+
+
+def schedule_command(
+    path: Path = typer.Argument(Path("."), help="Agent folder"),
+    input: list[str] = typer.Option([], "--input", help="An input as key=value, repeatable. The same inputs every run"),
+    cron: str | None = typer.Option(None, "--cron", help="Use this cron schedule instead of the manifest's, if it allows changes"),
+    now: bool = typer.Option(False, "--now", help="Run once right away, then keep to the schedule"),
+):
+    """Run the agent on its schedule, locally, until Ctrl+C."""
+    project_dir = path.resolve()
+    try:
+        manifest = load_manifest(project_dir / "manifest.yaml")
+    except ManifestValidationError as e:
+        render_issues(e)
+        raise typer.Exit(1) from e
+
+    declared = manifest.triggers.schedule
+    if cron and declared and not declared.consumer_can_change:
+        rprint("[red]✖[/red] this agent's schedule can't be changed (consumer_can_change: false)")
+        raise typer.Exit(1)
+    expr = cron or (declared.cron if declared else None)
+    if not expr:
+        rprint("[red]✖[/red] no triggers.schedule in manifest.yaml — add one, or pass --cron '0 9 * * 1-5'")
+        raise typer.Exit(1)
+    try:
+        ScheduleSpec(cron=expr)  # same validation as the manifest
+    except Exception as e:
+        rprint(f"[red]✖[/red] {e}")
+        raise typer.Exit(1) from e
+
+    # A scheduled run has nobody to ask; `gravity run` then treats approvals as "no".
+    os.environ["GRAVITY_UNATTENDED"] = "1"
+    memory = "keeps memory between runs" if manifest.state else "no memory between runs (no `state` in the manifest)"
+    rprint(f"[bold]{manifest.name}[/bold] on [cyan]{expr}[/cyan] · {memory} · Ctrl+C to stop")
+
+    runs = 0
+    try:
+        if now:
+            _tick(project_dir, input, runs)
+            runs += 1
+        while True:
+            at = next_run(expr, datetime.now())
+            rprint(f"[dim]next run {at:%a %d %b %H:%M}[/dim]")
+            time.sleep(max(0.0, (at - datetime.now()).total_seconds()))
+            _tick(project_dir, input, runs)
+            runs += 1
+    except KeyboardInterrupt:
+        rprint(f"\n[dim]stopped after {runs} run(s)[/dim]")
+
+
+def _tick(project_dir: Path, inputs: list[str], done: int) -> None:
+    rprint(f"\n[bold]scheduled run {done + 1}[/bold] · {datetime.now():%a %d %b %H:%M}")
+    try:
+        run_command(project_dir, input=inputs, llm_url=None, reply=None)
+    except typer.Exit as e:
+        if e.exit_code:
+            rprint(f"[yellow]⚠[/yellow]  run {done + 1} failed (exit {e.exit_code}); the schedule carries on")

gravity_cli/commands/tools.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from .. import api
+
+console = Console()
+
+
+def tools_command(
+    search: str = typer.Argument(None, help="Only show tools whose name contains this"),
+):
+    """The tool catalog: what you can put in permissions.tools."""
+    catalog = api.get("/api/cli/tools")
+
+    if search:
+        catalog = [t for t in catalog if search.lower() in t["name"].lower()]
+
+    table = Table()
+    table.add_column("name")
+    table.add_column("description")
+    table.add_column("scopes")
+    for t in catalog:
+        table.add_row(t["name"], t.get("description", ""), ", ".join(t.get("scopes", [])))
+    console.print(table)