f0911e65ed
New AI.dev/CHEATSHEETS/ reference set for delegating to terminal AI agents: - README.md: comparison matrix, 'which CLI?' decision guide, official-docs links, cross-CLI rules + ByteLyst environment facts - devin-cli.md: sessions, --permission-mode dangerous vs --sandbox, resume, the sandbox-stall gotcha, delegation pattern + prompt preamble - claude-code-cli.md: REPL/-p/-c/--resume, permission+plan modes, slash commands, MCP - codex-cli.md: interactive vs codex exec for CI, sandbox x approval matrix, config.toml Flags hedged with 'confirm via --help' since they drift between versions; durable value is the ByteLyst workflow. Does not reference .devin/config.local.json contents.
127 lines
6.4 KiB
Markdown
127 lines
6.4 KiB
Markdown
# 🤖 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`)._
|