# acsetra — the Runner CLI

A thin client for building and running **hosted Runner apps** from your terminal.
It holds no framework logic: every authoring command serializes to `{op, args}`
and is POSTed to the hosted API, where validation, reserved-code guards, and
doctor compiles all run server-side. You get the *grammar* of the framework, not
its implementation.

## Install

```bash
pipx install acsetra        # recommended (isolated)
# or: pip install acsetra
runner signin
```

Exposes three console scripts — `runner` (primary), `acsetra` (brand alias), and
`r` (continuity with `./r`).

## Quick start

```bash
runner signin                              # device-flow sign-in; caches a token
runner whoami
runner app create crm --label "CRM"        # create an app scope in your workspace
runner set put crm contacts ada --json '{"role":"eng"}'
runner read contacts -S <workspace>.crm
runner doctor <workspace>.crm && runner compile <workspace>.crm
runner auth crm                            # gate the app behind pen.acsetra.com sign-in
runner dev <workspace>.crm                 # open the app's hosted surface in your browser
```

## How it fits together

- `runner signin` runs the OAuth device flow: it prints a URL + code, you approve
  in the browser, and the CLI caches a token at `~/.config/acsetra/credentials` (0600).
- `runner docs pull` writes `CLAUDE.md` + `.runner/docs/*` — a compact model of the
  framework, the exact command grammar, and a live skeleton of your app — so a
  coding agent (Claude Code) has the context it needs to build with `runner`.
- The hosted DB is the source of truth. Local files are **instructions and mirrors**,
  never runtime source. `runner checkout` produces disposable working copies under
  `.tmp/` for grep and inspection; `runner dev <app>` just opens the live hosted
  surface in your browser.

## Environment overrides

| Var | Meaning |
|---|---|
| `ACSETRA_API_BASE` | hosted API origin (default `https://pen.acsetra.com`) |
| `ACSETRA_TOKEN` | bearer token (skips the cached credential) |
| `ACSETRA_WORKSPACE` | act in this workspace slug |
| `ACSETRA_SCOPE` | default app scope for `-S`-less commands |

Run `runner help` for the full verb list.
