Sourcegraph Amp CLI Cheatsheet - Terminal AI Coding Agent Full Reference
The common way to use a terminal coding agent is to open one foreground session and keep talking to it: halfway through a task you forget what you were doing, and the context degrades. Amp is designed against that, using threads to isolate tasks, letting long runs continue in the background while the foreground handles the next one-off question. This table groups installation and auth, single-shot questions, thread management, background execution and integration, and practical techniques, covering how to start and resume a thread and how to choose between amp and amp -x by intent. The decision rule is task shape: a single question needs no thread, iterative work with history worth reviewing does, and anything long or interactive belongs in the background. Reach for it when you want a long job running while you keep working, when calling a model headlessly in CI for a batch inspection, or when output must feed a script as a quality gate. The extra cost is managing threads; what you buy is context that stays clean.
Install & Auth 5
npm install -g @sourcegraph/ampamp --versionamp loginamp logoutexport AMP_API_KEY=...One-shot Prompts 5
amp "refactor user-auth to use the new session API"amp -x "list all TODO comments in this repo"amp --model claude-opus "write a CSV parser function"amp --no-streamamp --helpThread Management 5
amp threadsamp threads newamp threads continue <id>amp threads listamp --resumeBackground & Integration 5
amp -x "run the test suite" & --json "..."amp --cwd /path/to/repo "..."AMP_API_KEY=... amp -x "..."amp --verboseTips 5
amp -x is execution, amp is conversationIsolate context per topic with threadsCI runs -x with AMP_API_KEY--json feeds scriptsSwitch --model by needCommand Examples
One-shot question with an initial prompt
amp "Refactor user-auth to use the new session API"A one-shot like this does not deserve its own thread. When the work has to happen outside your current directory, pin it explicitly with amp --cwd /path/to/repo "...".
Push a slow test suite into the background
amp -x "run the test suite" &Execution mode plus backgrounding frees the terminal immediately. Use the wait to open a separate thread for something else rather than interleaving inside this one.
Make the output machine-parseable
amp --json "Find unused exports"Branch on the event type to decide status instead of parsing the last line of text. For headless CI, prefix the command with AMP_API_KEY=...
Return to an earlier thread to finish unfinished work
amp threads continue <id>Get the ID from amp threads list. Use amp threads list when you want a script-friendly listing, and amp threads when a human is browsing interactively.
Common Pitfalls
- AMP_API_KEY is a live credential. Exporting it in a CI environment tends to leak it into logs — inject it through the platform secret store, never echo it, and never commit it to a config file.
- Interleaving two requirements in one thread contaminates the context and makes it impossible to tell later which edits belonged to which task. Open a fresh thread with amp threads new for every parallel task.
- Headless runs launched straight into CI frequently waste a cycle on missing credentials or a wrong working directory. Run the identical prompt interactively once locally to confirm it works.
- A wrong amp --cwd makes the agent read a different repository, or edit far more files than you intended. Verify the path, then check working tree status before you let it run.
- The --json output is a stream of events, not one JSON document, so reading only the last event misreports status. And leave git status clean before headless runs — the agent edits files.
Tips
- Sourcegraph Amp is a terminal coding agent from Sourcegraph that can sit on multiple models;
ampleans conversational,amp -xleans execution — pick by intent. - The threads mechanism isolates context per task so a long conversation does not pollute another — handy in complex projects.
- In CI/headless, use
AMP_API_KEYwithamp -xfor automation without interactive login. --jsonoutput feeds scripts for programmatic parsing (quality gates, batch audits).
FAQ
How do I choose between amp and amp -x?
amp leans conversational: you bring a prompt and it tends to discuss the approach and write code. amp -x leans operational: it takes the same prompt but prefers to go straight to editing files and running commands. Pick by task shape, not by how long the prompt is — amp for questions needing back-and-forth, amp -x for work that is already specified.
Why start a separate thread for every task?
A thread is a context boundary. amp threads new opens one, amp threads continue with an ID picks an old one back up, and amp --resume returns to the most recent. Alternate two requirements inside one thread and the agent blends the files, conventions, and conclusions of both — by the time you review, nothing clearly belongs to which task.
How do I run Amp in CI where there is no login session?
Provide the key with export AMP_API_KEY=... and drive it through amp -x for headless work, so nothing depends on an interactive login. The reliable routine is to run the exact same prompt interactively once locally first, confirm permissions and credentials, and only then let CI take it.
What problem does amp --json actually solve?
It turns the output into a stream of structured events that a script can branch on by event type, instead of scraping text with regular expressions. It is the usual building block for quality gates and batch sweeps: check whether a given event type appeared, count tool invocations, confirm the run terminated cleanly — rather than grabbing the last paragraph of text.
What do I do with a long task that would otherwise block the terminal?
Append & to push it into the background: amp -x "run the test suite" &. The prompt comes straight back so you can start another thread on the next question and collect the result later. For finer detail on what the agent is doing tool call by tool call, add --verbose.
Official References
Each command links to its official documentation below, so you can verify the latest usage and read deeper.
Maintained by LaoHand
Publicly updated on Aug 23, 2026, continuously proofread against official docs.
Contact Us
Wrong command or description? Send us corrections, business inquiries or product feedback by email.
Contact Us