CLI Agent Onboarding

Agent-first onboarding for Breyta (Codex, Claude Code, Cursor, Gemini CLI, and other agents that can run local CLI commands).

Install the CLI

If breyta --version fails, install the CLI:

macOS (Homebrew):
- brew tap breyta/tap
- brew install breyta
Prebuilt binaries: download a release artifact from https://github.com/breyta/breyta-cli/releases and put breyta on your PATH.
From source (Go): go install github.com/breyta/breyta-cli/cmd/breyta@latest

Quick Answer

Install the breyta CLI, then run:

breyta init --provider <codex|cursor|claude|gemini>
breyta auth login
breyta workspaces list
breyta flows search "<problem keyword>" --limit 5
breyta flows templates search "<problem keyword>" --limit 5

breyta init installs the Breyta skill bundle (optional) and creates a local breyta-workspace/ folder with an AGENTS.md file that your agent can read reliably.
The bundle includes SKILL.md, task playbooks, and focused references. Agents
should read SKILL.md first, then load the playbook or reference named by its
loading matrix before creating, editing, releasing, publishing, changing
outputs/tables, touching provider APIs/models, or changing reliability behavior.
That generated AGENTS.md is intended to push a connection-first, definition-first build order:
inventory and test connections first, design :requires slots around business
capabilities, then build top-level :templates, :functions, packaged
:steps, reusable :agents, and only then the final :flow orchestration.

Why `AGENTS.md` Matters

Many agent tools only load project instructions from the active folder when you open it as a workspace/project (or when you start a new agent session in that directory).

After breyta init, open ./breyta-workspace/ in your agent tool (or cd into it and restart the agent) so it picks up AGENTS.md.

Copy/Paste Snippet (give this to your agent)

You are my Breyta onboarding assistant.

Goal: install the Breyta CLI, set up reliable agent context (AGENTS.md), authenticate, then help me create and run my first flow.

Please:
1) Check if `breyta` is installed: `breyta --version`.
2) If it isn’t installed, help me install it:
   - macOS (Homebrew):
     - `brew tap breyta/tap`
     - `brew install breyta`
   - manual download (all platforms): https://github.com/breyta/breyta-cli/releases
   - optional (if Go is installed): `go install github.com/breyta/breyta-cli/cmd/breyta@latest`
3) Ask which agent tool I’m using (Codex, Cursor, Claude Code, Gemini CLI) and run:
   - `breyta init --provider <codex|cursor|claude|gemini>`
4) Tell me to open the created `breyta-workspace/` folder in my agent tool (or `cd` into it and restart the agent) so it reads `AGENTS.md`.
5) Authenticate (and create an account if needed): `breyta auth login`
6) Verify:
   - `breyta workspaces list`
   - `breyta flows search "<problem keyword>" --limit 5`
   - `breyta flows templates search "<problem keyword>" --limit 5`
   - `breyta connections list`
   - `breyta connections test <connection-id>` for the connection likely to be used
7) Help me build my first flow using the CLI loop:
   - first search reusable patterns and existing data:
     - `breyta flows search "<problem or integration>" --limit 5`
     - `breyta flows grep "<literal step/tool/config>" --limit 5` when metadata is insufficient
     - `breyta flows templates search "<problem or integration>" --limit 5`
     - `breyta flows templates grep "<literal step/tool/config>" --limit 5` when template metadata is insufficient
     - `breyta docs find "<primitive or command>" --limit 5 --format json`
     - `breyta docs show <slug> --section "<heading>"` for one focused page section
     - `breyta resources search "<existing data>" --limit 5` and `breyta resources read <resource-uri> --limit 5` when the flow should reuse prior reports, uploads, or run output
   - then inventory and validate the reusable connections the flow will need:
     - `breyta connections list`
     - `breyta connections test <connection-id>` for likely candidates
     - `breyta connections show <id>` for likely candidates
     - design stable `:requires` slot names around business capability (`:github-api`, `:crm`, `:llm`) rather than transient provider names
   - then shape the reusable flow surfaces before writing orchestration:
     - start with a small installable-minded contract: `:requires`, `:invocations`, `:interfaces`, output shape, side effects, and `:concurrency`
     - `:templates` for prompts, request bodies, and large static content
     - `:functions` for normalization, shaping, and result projection
     - `:steps` for packaged heavy built-in step configs
     - `:agents` for reusable reviewer/fixer/coordinator agent definitions
     - then wire them together in `:flow`
   - keep iterations small:
     - push a minimal manual-interface skeleton before adding integrations
     - add one connection, provider call, table, job, agent, or child flow at a time
     - default to `:persist` for unknown/unbounded payloads and pass resource refs instead of large inline bodies
     - when transforming a persisted blob, pass the persisted step result into a `:function` step and hydrate it with `:load`
     - keep functions map-oriented; use Clojure map access plus `json/*` and `breyta.sandbox/*` helpers instead of custom parser/guard layers
     - use bounded paging with max pages/items and durable writes before cursor advancement for larger datasets
   - design the final output artifact before implementing the last expression:
     - default to a readable Markdown viewer for human-facing flows
     - use `breyta-resource` fenced blocks for embedded tables, charts, downloads, media, nested Markdown, text, and JSON resources
     - do not expose raw debug maps, `res://` refs, or implementation fields unless structured data is the intended product
	   - `breyta flows pull <slug> --out ./flows/<slug>.clj`
	   - edit `./flows/<slug>.clj`
	   - `breyta flows lint --file ./flows/<slug>.clj`
	   - `breyta flows push --file ./flows/<slug>.clj`
   - `breyta flows configure check <slug>`
   - `breyta flows run <slug> --input '{"n":41}' --wait`
   - flows may declare one manual interface; if you need explicit selection, use `breyta flows run <slug> --interface-id <id> --input '{"n":41}' --wait`
   - model alternate manual entry modes as invocation inputs such as `mode`, not as multiple manual interfaces
   - optional: `breyta flows validate <slug>`
   - inspect draft changes before release: `breyta flows diff <slug>`
   - iterate in draft until behavior is correct
   - release once after explicit approval, with a markdown note: `breyta flows release <slug> --release-note-file ./release-note.md`
   - edit the version note later if needed: `breyta flows versions update <slug> --version <n> --release-note-file ./release-note.md`
   - verify live target: `breyta flows show <slug> --target live`
   - smoke-run live target: `breyta flows run <slug> --target live --wait`
8) Use product docs when needed:
   - search by primitive: `breyta docs find "files materialize" --limit 5 --format json`
   - search by exact phrase: `breyta docs find "\"draft setup\"" --limit 5 --format json`
   - search by command path: `breyta docs find "source:cli flows configure check" --limit 5 --format json`
   - search by API/runtime source: `breyta docs find "source:flows-api agent definitions" --limit 5 --format json`
   - search by error text when stuck: `breyta docs find "\"Bad credentials\"" --limit 5 --format json`
   - `breyta docs show <slug>` for the best narrow hit; use `--section <heading>` first and `--full` only when the complete page is needed
9) Use CLI help for flag truth:
   - `breyta help <command...>`
10) Use the installed Breyta skill bundle when working on flows:
	   - read `SKILL.md` first
	   - load the relevant bundled playbook or `references/` file before creating or editing behavior
	   - use `playbooks/author-flows.md` for create/edit/template/resource-ref work
	   - use `playbooks/debug-and-verify.md` for failed runs, output proof, and UI mismatch
	   - use `playbooks/release-and-install.md` for draft/live/release/install work
	   - use `playbooks/public-and-marketplace.md` for public/end-user/Discover/marketplace work
	   - use `playbooks/advanced-reliability.md` for fanout, paging, waits, retries, and idempotency
	   - use `references/outputs-and-tables.md` for outputs, Markdown reports, resource embeds, raw viewers, JSON resource embeds, persisted resources, and table viewers
	   - use `references/runtime-data-shapes.md` for resource refs, `:persist`, `:load`, and function input shapes
	   - use `references/provider-api-freshness.md` for external APIs and model ids

Prefer small, incremental changes and verify each step before moving on.

Make Skills Reliable (Optional)

Some tools auto-load skills; others do not. If you want your agent to always use the Breyta skill bundle when Breyta is involved:

install it (or refresh it) with breyta skills install --provider all or a single provider such as --provider codex
explicitly reference the installed skill file path from your persistent project instructions (for example AGENTS.md)

Typical install paths:

Codex: ~/.codex/skills/breyta/SKILL.md
Claude Code: ~/.claude/skills/breyta/SKILL.md
Cursor: ~/.cursor/rules/breyta/RULE.md
Gemini CLI: ~/.gemini/skills/breyta/SKILL.md

Suggested compact line for AGENTS.md:

For Breyta work, load the installed Breyta skill first, then only the playbook/reference for the touched surface. Treat missing/stale skill warnings as drift. Use bounded search (docs find, flows search/grep, flows templates search, resources search with --limit 5). Build small draft slices, lint before push, pass large data as resource refs, and verify the same interface/input/target the user will exercise. Draft is staging; live is released/runtime.