Metadata-Version: 2.5
Name: acsetra
Version: 0.1.80
Summary: Runner CLI — author and run hosted Runner apps from your terminal (the `runner` command).
Project-URL: Homepage, https://acsetra.com
Author: Acsetra
License: MIT
Keywords: acsetra,agent,cli,low-code,runner
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# 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                              # you + every org you can reach, with access (owner/edit/view)
runner app create <org>.crm --label "CRM"  # create an app scope in THAT org (any org you can edit)
runner set put <org>.crm contacts ada --json '{"role":"eng"}'
runner read contacts -S <org>.crm
runner doctor <org>.crm && runner compile <org>.crm
runner auth <org>.crm                      # gate the app behind home.acsetra.com sign-in
runner dev <org>.crm                       # open the app's hosted surface in your browser
runner open <org>.crm                      # reuse/create its paired Chrome tab
runner notify <org>.crm --title Ready
runner tabs
```

Every command names its target by **full scope path `<org>.<app>`** — the first
segment is the org, and that is what routes the command. Nothing is pinned per
project: you may read every org you belong to and author in any org where your
share access is **edit** (granted in Runner Command → Share). A bare leaf (`crm`)
only resolves against the token's home org — `runner use <slug>` changes that
default, but full paths never need it.

## 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/*` — concise doctrine and
  a framework model for Claude Code. Exact grammar always comes from
  `runner <group> <subverb> --help`, so it cannot drift from the installed client.
- `runner open`, `focus`, `notify`, and `tabs` use the paired Runner Chrome
  extension. CLI and ChatGPT MCP write the same short-lived browser intents.
- 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://home.acsetra.com`) |
| `ACSETRA_TOKEN` | bearer token (skips the cached credential) |
| `ACSETRA_WORKSPACE` | home org slug for bare-leaf scopes (full `<org>.<app>` paths route themselves) |
| `ACSETRA_SCOPE` | default app scope for `-S`-less commands |

Run `runner help` for the full verb list.
