Quickstart

This guide gets you from installing the CLI to a running pipeline in one continuous session — mostly in your terminal, with one short hop to your browser to create a project. ~10 minutes.

Install the CLI
Terminal window
```
npm i -g @boboddy/cli
```
See Installation for the Bun alternative, platform details, and AI-provider setup.
Initialize your project

From the root of your repository:
Terminal window
```
cd my-repo
boboddy init
```
init walks up from your current directory to find the real repository root (submodule-safe), then prints the repo path and remote it resolved — so a walk into a repo you didn’t realize you were in is never silent.

From there it handles both logins for you:
- OpenCode. If it doesn’t detect a configured provider — neither an opencode auth login nor a recognized env var such as ANTHROPIC_API_KEY — it runs opencode auth login inline and waits for you to finish before continuing.
- Boboddy. If you aren’t signed in, it runs the device-flow login for you.
If a project already matches this repo’s git remote, init skips straight to step 3. Otherwise, it opens your browser to a pre-filled Create Project page:

The project-creation page defaults to picking a repo from GitHub over entering one manually — take it if the option’s there. A linked repo keeps ingesting new and updated issues as work items on an ongoing basis; a manually-created project never syncs anything automatically. See Integrations for what each path gets you and how to link one later if you skip it now.

Finish creating the project in the browser, then switch back to your terminal and press Enter to continue. init re-resolves the project it just found and writes .boboddy/boboddy.jsonc with the projectId, so later commands don’t need it passed explicitly.

It also checks for a .devcontainer/devcontainer.json and tells you if there isn’t one — that’s a notice, not a blocker; the design session in the next step writes one for you if it’s missing. init never authors a pipeline itself and never analyzes your repo — the design agent does both, and it’s what runs next.
Design your first pipeline

init launches straight into an interactive session with a pipeline-designer agent, seeded with a work item you pick — one of the project’s recently-ingested items (searchable, not just the most recent few), or paste a ticket URL or describe one in a sentence and it creates the item for you. Every session designs around a real work item, so pick something typical rather than your weirdest edge case.

Moments after the session opens, it kicks off a quick health check of the container and OpenCode runtime in the background — purely advisory, so it doesn’t hold up the conversation while it runs.

The agent reads your repository first — including any .opencode/opencode.json or .opencode/tools/ you already have, since every MCP server or tool declared there already loads for every step, so it won’t ask whether those exist. It won’t ask about your stack either. It opens on the goal — what should come out the other end when a ticket like this one arrives? — and everything after that is asked through the item you picked, one question at a time:
- The deliverable. If that ticket landed overnight and an agent picked it up, what would you want waiting for you in the morning, and what would you have to see to trust it?
- What the execution environment can reach. Walk it through your own process for that ticket, step by step — what’s the first thing you’d do, and which tool would you use for it, then what’s next? Each tool you name either already loads (it’s in your .opencode/ config) or becomes a new MCP server for the pipeline. “Nothing but the repository” is a completely normal answer and still supports a good pipeline.
- What must never be touched. Working that ticket, what would you be angry to find an agent had done? Production writes, customer data, anything that sends email or charges money.
If one of those new tools needs a secret — an API key, a token, a connection string — it never asks for the value. It asks for the variable name and writes it to .boboddy/.env.example, then tells you at the end which variables you need to fill in: copy that file to .boboddy/.env and put the real values there yourself. .boboddy/.env is never something the agent writes.

It then proposes two or three ranked pipeline designs — filtered to what you actually said is reachable — and builds the one you pick, plus a default-pipeline-assignment.ts so incoming work items route to it. Because the designer only proposes what your environment can actually support, a repo with no dev container gets a pipeline built entirely from no_workspace steps: the agent works on the host in a scratch directory instead of cloning your repo, so nothing here needs Docker. If a step does need your code, the agent writes a .devcontainer/devcontainer.json for you first — see Setting up a Dev Container if you’d rather write one by hand, or Execution mode for the workspace/no_workspace distinction.

Finally, the agent typechecks the definitions and runs boboddy pipelines push.

Shell commands are gated by permission prompts. The prompt on boboddy pipelines push is your confirmation — nothing reaches the server until you approve it.

design needs a real terminal; it won’t work through a pipe or in CI. It’s also re-runnable: run it again (boboddy pipelines design) with a different work item and it reads your existing definitions and iterates on them rather than starting over. In those sessions it tells you up front how big a change it thinks you need — tweak an existing pipeline, route these items to one, or add a new pipeline — and waits for you to agree before it edits anything. Same command for day one and day fifty.
Tip
Prefer to write the definitions yourself? boboddy pipelines init scaffolds a commented triage-and-plan.ts starter pipeline plus default-pipeline-assignment.ts for you to hand-edit — it’s the manual path and needs no AI provider:
Terminal window
boboddy pipelines init cd .boboddy/pipeline-builder && npm install # or bun/pnpm/yarn install npm run typecheck cd ../.. && boboddy pipelines push
See Defining Steps and Building Pipelines.
Verify and run

Once the definitions are pushed, design runs one more check before offering to queue anything: a full dry-run — container, OpenCode, and tool/MCP health — targeted at your new pipeline’s first step. This one is blocking: if it fails, nothing is queued, and re-running boboddy pipelines design is what picks the problem back up next time.

If it passes, design asks whether to run your new pipeline against the work item you designed around, right now. Say yes and it queues the run and starts a worker in the same terminal:
Terminal window
```
boboddy work
```
The worker claims the pending step execution, runs the step’s agent, and reports its signals back. Watch the pipeline view in the dashboard: each step’s advance policy reads those signals and decides whether the pipeline continues, blocks for a human, or completes. That advance-on-signal moment is the core of Boboddy.

Say no instead, and design prints the command to run it later — start a run from the work item’s executions drawer in the dashboard, or from a fresh work item, whenever you’re ready.

That’s a full pipeline run, designed and executed from a single command.

Next steps

Automate intake. If you skipped linking GitHub (or want to add Jira), connect one from your project’s settings — see Integrations for what syncs, how often, and the field mapping into work items.
Change how work items route. The default-pipeline-assignment.ts the agent wired up decides which pipeline starts for each incoming item — see Default Pipeline Assignment for the full rule API.
Scale up workers. See Running Workers for concurrency, polling, and branch options.

Project structure

After completing setup, your repo will have:

Directorymy-repo/
- Directory.boboddy/
  - boboddy.jsonc project config (projectId, optional branchPrefix)
  - .env.example variable names for secrets a step’s tools need, no values
  - .env your real secret values — you create this yourself, never committed
  - Directorypipeline-builder/ steps and pipeline definitions
    package.json SDK + zod deps, typecheck script
    tsconfig.json
    .gitignore
    <your-pipeline>.ts one file per pipeline
    default-pipeline-assignment.ts
    Directorynode_modules/ ignored
    …
    push.ts ignored; regenerated by every push
- Directory.devcontainer/
  - devcontainer.json execution environment (workspace-mode steps)

Everything in .boboddy/pipeline-builder/ is committed except node_modules/, lockfiles, and push.ts. Your pipeline and step definitions are source code — review them in pull requests like any other file.

.boboddy/.env.example only exists if a pipeline needs a secret — the design session writes it with variable names, never values, and tells you which ones to fill in. Commit it so teammates know what to set. Never commit .boboddy/.env — add it to your repo’s .gitignore if it isn’t covered already; it holds the real values and the design session never writes it for you.

Lockfiles are the surprising exclusion. boboddy pipelines push picks its runtime from whichever lockfile it finds in that directory, so committing one would force every teammate onto the same package manager. Each developer installs with the tool they already have.

Run npm run typecheck (or the bun/pnpm/yarn equivalent) inside .boboddy/pipeline-builder/ to validate your definitions before pushing.

Where to go next

Defining Steps — inputs, results, signals, and execution modes.
Building Pipelines — the pipeline() builder, input bindings, and additional pipeline input.
Pipeline Advancement — advancement policies and computed signals.