# 🤖 Devin CLI — Cheat Sheet

> **What it is:** Cognition's **Devin** as a terminal agent. You hand it a scoped task
> (ideally a self-contained roadmap), and it plans → edits → runs → verifies across many
> steps with minimal babysitting.
> **Best for:** Long-running, well-scoped delegations where you want to walk away — e.g.
> "validate and harden `tracker-web`'s test suite," or "execute this 5-task roadmap."
> **In this repo:** session config lives in `.devin/config.local.json` (**secret — never
> commit or print it**). A worked example is
> [`dashboards/tracker-web/docs/roadmaps/DEVIN_CLI_EXPERIMENT.md`](../../dashboards/tracker-web/docs/roadmaps/DEVIN_CLI_EXPERIMENT.md).

> ⚠️ **Flags drift between versions.** Run `devin --help` to confirm. This sheet captures
> the workflow + ByteLyst conventions, which are stable.
>
> **Official docs:** <https://docs.devin.ai>

---

## Install & auth

```bash
# Install per the official docs (https://docs.devin.ai), then verify + authenticate.
# (Confirm the exact subcommands for your version with `devin --help`.)
devin --help                # list available commands/flags
devin login                 # authenticate (or provide the API key Devin expects)
```

- Auth/state for this workspace is cached in `.devin/config.local.json` (mode `600`).
- That file may contain an **API token** → it is git-ignored; keep it that way.

## Launching a session

```bash
devin                                   # interactive TUI in the current dir
devin "validate the tracker-web tests"  # seed the first instruction inline
```

A Devin session shows a live **todo list** and streams its tool calls (reads, edits,
shell commands). You can interrupt at any time (Ctrl-C / Esc) — that shows up in the
log as `Canceled due to user interrupt` (this is **you**, not a permission block).

## Permission & sandbox modes

| Flag                          | Effect                                                        |
| ----------------------------- | ------------------------------------------------------------- |
| _(default)_                   | Asks before potentially destructive commands                  |
| `--permission-mode dangerous` | **Auto-approves** commands without prompting                  |
| `--sandbox`                   | Runs in an **isolated environment** (restricted fs / network) |

```bash
# Full autonomy, isolated:
devin --permission-mode dangerous --sandbox

# Full autonomy, direct access to the real pnpm workspace + corp proxy:
devin --permission-mode dangerous
```

> 🧠 **Gotcha (learned the hard way):** `--sandbox` can wall off the filesystem and
> network even when command _approval_ is automatic. ByteLyst work needs to (a) read
> sibling `packages/*` for `workspace:*` builds and (b) reach the corp proxy / Gitea
> tunnel for `pnpm`. If a sandboxed run stalls on install/build, **drop `--sandbox`**.
> `dangerous` mode never blocks; a stall is almost always sandbox scope.

## Session management

```bash
devin -r            # list recent sessions
devin -r <id>       # resume a specific session (e.g. `devin -r adaptable-comma`)
/exit               # leave the interactive session
```

Sessions are named (e.g. `adaptable-comma`); the CLI prints the resume command when you
exit. Resuming keeps the prior context + todo state.

## How to delegate well (the ByteLyst pattern)

Devin shines with a **self-contained roadmap file**. Don't free-form a vague goal —
point it at a doc that encodes scope, verify commands, and a done-definition. See
[`AI.dev/PROMPTS/`](../PROMPTS/) for reusable templates and the tracker-web experiment
doc for the gold-standard shape:

1. **Scope lock** — name the exact folder; forbid edits elsewhere (incl. shared packages).
2. **Verify commands** — give the literal `pnpm typecheck && pnpm lint && pnpm test && pnpm build`.
3. **Commit discipline** — one task = one conventional commit; flip the checkbox + paste
   the short-SHA in the same commit.
4. **No fabrication** — only check a box after its Verify passes; otherwise leave `- [ ]`
   with a one-line blocker.
5. **Done-definition** — full suite green from a clean state + a summary of SHAs.

Paste this preamble into the first instruction every time:

```text
Read AGENTS.md and AI.dev/SKILLS/agent-behavior-guidelines.md first.
Scope: ONLY <path>. Don't edit shared packages/.npmrc/docker-prep.sh.
Tests are sacred. Verify with: <exact commands>. Conventional commits.
Builds use `next build --webpack`. pnpm workspace; workspace:* deps link locally.
Only mark a task done after its verify passes — never fabricate. Commit + push per task.
```

## Troubleshooting

| Symptom                                         | Likely cause                                         | Fix                                        |
| ----------------------------------------------- | ---------------------------------------------------- | ------------------------------------------ |
| `Canceled due to user interrupt`                | You pressed Ctrl-C/Esc or `/exit`                    | Resume: `devin -r <id>`                    |
| Stalls on `pnpm install` / build in `--sandbox` | Sandbox blocks fs/network                            | Re-run **without** `--sandbox`             |
| Can't find `@bytelyst/*` packages               | Sandbox can't see sibling `packages/*`               | Run from the monorepo; drop `--sandbox`    |
| `pnpm` network errors                           | Corp proxy / Gitea tunnel not reachable from sandbox | Run on host (proxy active) without sandbox |
| Asks for approval despite `dangerous`           | Flag typo / older binary                             | `devin --help`; update the CLI             |

## Quick-reference card

```text
devin                              # start interactive session here
devin --permission-mode dangerous  # auto-approve commands (recommended for delegations)
   add --sandbox                   #   ...but only if the task needs no workspace/network
devin -r                           # list sessions
devin -r <name>                    # resume a session
/exit                              # end session (prints resume command)
```

---

**Related:** [`claude-code-cli.md`](./claude-code-cli.md) · [`codex-cli.md`](./codex-cli.md) ·
[`../PROMPTS/`](../PROMPTS/) · [`../SKILLS/agent-behavior-guidelines.md`](../SKILLS/agent-behavior-guidelines.md)

_Last updated: 2026-05-28 · verify flags against your installed version (`devin --help`)._