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 list

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.

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 list`
7) Help me build my first flow using the CLI loop:
   - `breyta flows pull <slug> --out ./flows/<slug>.clj`
   - edit `./flows/<slug>.clj`
   - `breyta flows push --file ./flows/<slug>.clj`
   - `breyta flows configure check <slug>`
   - `breyta flows run <slug> --input '{"n":41}' --wait`
   - 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:
   - `breyta docs find "<topic>"`
   - `breyta docs show <slug>`
9) Use CLI help for flag truth:
   - `breyta help <command...>`

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 <codex|cursor|claude|gemini>
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 line to paste into AGENTS.md: