Gemini CLI is most useful when you treat it like a terminal-native debugging partner, not a magic code vending machine. The sweet spot is giving it the failing command, the relevant files, and a narrow objective, then keeping the loop tight enough that every proposed change stays explainable.
This post covers a practical Gemini CLI workflow for debugging production-ish issues, local repro failures, and flaky dev setup problems without giving the model broad, unsupervised control.
Why terminal-first debugging works well with Gemini CLI
Most debugging already starts in the terminal: a test fails, a build breaks, a service exits unexpectedly, a linter starts complaining after a refactor, or a deploy script works on one machine but not another. Gemini CLI fits this flow because it can stay close to the evidence. You can hand it the exact failing output, let it inspect only the files that matter, and have it propose the next command or patch instead of forcing it to reconstruct the whole situation from memory.
That is a better pattern than dropping a giant repo into context and asking what is wrong.
The debugging loop I actually recommend
- Capture the failing command and raw output.
- Ask Gemini CLI for a read-only diagnosis first.
- Narrow the scope to the smallest relevant files.
- Let it propose one fix path at a time.
- Rerun the exact verification command.
- Only then accept edits or commit the patch.
Start with plan mode, not edits
Gemini CLI's plan mode is useful for the first pass because it forces a diagnosis before action. That matters when the visible failure is only a symptom.
The command `pnpm test src/api/user.test.ts` fails with the output below.
Do not edit files yet.
Explain the most likely root causes, what evidence supports each one,
and which file or command you would inspect next.This works because it gives Gemini CLI the exact failing command, blocks premature editing, and asks for ranked hypotheses instead of a single confident guess.
Feed it command output like an incident artifact
A lot of AI debugging goes sideways because the model gets a paraphrase instead of the actual logs. Paste the real stderr, stack trace, or test diff.
Command:
python -m pytest tests/test_auth.py -k refresh_token
Output:
E AssertionError: expected 401, got 200
...Real output gives the model anchors: filenames, line numbers, error classes, environment assumptions, and failing invariants.
Keep context small on purpose
Terminal debugging gets worse when the model sees too much irrelevant code. Give Gemini CLI a narrow search space: the failing command, the error output, the test or entrypoint involved, the config file that shapes runtime behavior, and one or two adjacent implementation files. If the issue smells like infrastructure or environment drift, also include the exact startup script, container file, or CI step.
Use shell access for facts, not exploration theater
Gemini CLI can execute shell commands, which is handy, but the point is to collect evidence quickly. Prefer short, high-signal commands that answer a specific question.
rg "refresh_token|401|auth" src tests
cat package.json
pnpm test src/api/user.test.ts
git diff -- src/api/auth.tsThat is enough to identify the surface area, inspect the current state, and confirm whether a candidate fix worked.
A reliable prompt pattern for the middle of the session
Given the failing test, the current implementation, and the config shown above:
- state the most likely root cause in one paragraph
- show the minimum code change needed
- explain one risk of that change
- list the exact command to verify itThis pattern is great because it bundles the claim, the patch, the risk statement, and the verification step into one reviewable answer.
Example workflow: debugging a broken dev server
`npm run dev` exits immediately after a config refactor.
I pasted the stderr below.
Inspect only package.json, vite.config.ts, src/config.ts, and src/main.ts.
Do not edit yet. Give me the top 3 likely causes and the fastest check for each.Then, once Gemini CLI narrows it down, ask for the smallest patch, why it broke now, and the exact verification command. That is the right level of control.
Where people burn time with AI debugging
Asking for a fix before a diagnosis
That often produces a patch that changes visible behavior without addressing the root cause.
Giving a summary instead of the artifact
Paraphrased logs remove the clues that matter.
Letting the session sprawl
If the model has seen too many files and unrelated commands, it starts to generalize from noise.
Verifying with a different command than the failure
Always rerun the original failing command first, then broaden the checks.
Security and safety guardrails that are worth keeping
- Start in read-only or diagnosis-first mode when the failure is unclear.
- Keep shell usage scoped to inspection and verification.
- Require human review before multi-file edits.
- Be careful with secrets in pasted logs and environment output.
- Prefer repo-local context files and ignore rules over ad hoc prompt dumping.
A small workflow that scales surprisingly well
failing command
-> raw output
-> read-only diagnosis
-> minimal patch proposal
-> exact verification command
-> human reviewThat workflow works for test failures, build regressions, broken scripts, misconfigured dev environments, and a decent chunk of CI debugging too.