learning_ai_common_plat/AI.dev/CHEATSHEETS/devin-cli.md

🤖 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.

⚠️ 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

# 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

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)

# 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

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/ 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:

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

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 · codex-cli.md · ../PROMPTS/ · ../SKILLS/agent-behavior-guidelines.md

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