Cline CLI Guide: Use an AI Coding Agent From Your Terminal

This Cline CLI guide shows how to use an AI coding agent from your terminal: install the command-line tool with Node.js, run cline auth, then start an interactive session with cline or give it a bounded task such as cline "Add validation tests for the signup handler". Treat it as a tool-using collaborator—not a text generator—because it can inspect files, edit code, search the repository, and run shell commands; begin with reviewable tasks and keep tool approval enabled while you learn. [1][2]

What is Cline CLI?

Cline CLI is a terminal interface for an AI coding agent. The distinction matters: a chat assistant returns suggestions, while an agent can gather context from the working tree, decide which tools to call, execute those tools, observe the output, and continue until it reaches a stopping point or needs your input. In the CLI, the built-in tool set includes reading and editing files, applying patches, ripgrep-powered search, shell execution, web fetching, and asking questions. [2]

That loop is useful when the task has feedback the agent can consume. “Find the failing test, explain the likely cause, make the smallest fix, and run the focused test again” is agent-shaped work. “What does this regex mean?” generally is not: a normal chat response is faster and creates no risk of an unnecessary workspace change.

How do you install Cline CLI?

Install Node.js 20 or newer first; the official documentation recommends Node 22. Then install the CLI globally, verify that your shell can find it, and open the provider-authentication flow.

node --version
npm install -g cline
cline version
cline auth

cline auth is the important setup step. It opens the provider configuration flow, where you select how the agent will reach a model. The documented paths include Cline’s usage-billed provider, a subscription provider, and bring-your-own-key credentials for cloud or local runtimes. Do not paste keys into a repository config file or a prompt; use the auth flow or environment variables supported by your chosen provider. [1][3]

If cline: command not found appears after installation, the usual cause is that npm’s global binary directory is absent from PATH. Confirm the global install location, update your shell profile if needed, restart the shell, and rerun cline version. If the command starts but model requests fail, run cline doctor and then revisit cline auth before debugging your project.

How do you start an AI coding agent in the terminal?

Use cline by itself for a multi-turn terminal session. This is the right default for unfamiliar repositories, design work, or any task where you expect to clarify constraints as the agent learns more.

cd ~/src/payments-service
cline

For a single, well-scoped request, pass the task as an argument. Cline’s CLI reference supports both direct prompts and prompts piped through standard input. A direct prompt begins in Act mode unless you request plan mode, so explicitly ask for a plan or use --plan when you want analysis before changes. [1]

# Ask for a proposal before changing the worktree
cline --plan "Trace how refunds are authorized. Propose the smallest change needed to reject duplicate refund requests, including files and tests. Do not edit anything yet."

# Run a bounded implementation task
cline "In src/rateLimit.ts, add tests for a reset-at-boundary case. Run only the relevant test file. Do not change public APIs."

# Give the agent text through stdin
git diff origin/main | cline "Review this diff for correctness risks, missing tests, and security issues. Do not modify files."

How should you prompt an AI coding agent?

The best terminal-agent prompt reads more like a compact engineering ticket than a request for an answer. State the desired outcome, the relevant scope, constraints the agent must not violate, and the evidence required before it can call the job done. This reduces aimless exploration and gives you concrete criteria for reviewing its work.

• Outcome: “Add idempotency protection to the refund endpoint.”
• Scope: name the directory, service, endpoint, issue number, or failing test if you know it.
• Constraints: preserve API compatibility, avoid schema migrations, do not alter unrelated formatting, or use the existing test framework.
• Verification: run a particular test command, typecheck, lint, or report tests that cannot run locally.
• Stop condition: ask before changing dependencies, migrations, secrets, infrastructure, or production configuration.

Avoid prompts such as “fix the auth code” unless you explicitly want exploration. A stronger first request is: “Inspect authentication middleware and its tests. Identify the highest-confidence bug behind unauthorized refresh requests. Return a plan, affected files, and the test you would add; do not edit yet.” Once the plan is credible, ask for the implementation in a second turn. Splitting discovery from execution makes wrong assumptions visible while the change is still cheap.

How do Plan mode and approval controls work?

Plan mode is a practical guardrail: it asks the agent to investigate and propose a route rather than immediately taking actions. Invoke it with -p or --plan; use the normal task invocation when you are ready for execution. The CLI also has a global --auto-approve setting. Current documentation says tool auto-approval is enabled by default in ordinary CLI use, so set it explicitly to false whenever you want a confirmation before each tool operation. [1][4]

cline --plan "Map the data flow from webhook receipt to invoice creation. Identify likely failure points and a test strategy."

cline --auto-approve false "Inspect and modify this repository to add a regression test for issue #418. Explain each command before it runs."

Approval is not a substitute for judgment. Read commands that alter state especially closely: package installs, database commands, destructive filesystem operations, credential access, deployments, or scripts downloaded from the network. Work in a clean branch, inspect the diff after a task, and run your normal formatter, test suite, static analysis, and security checks yourself. An agent’s successful command exit does not prove the product behavior is correct.

How do you run Cline CLI in scripts and CI?

Use non-interactive runs only for repetitive jobs with constrained inputs and machine-readable outputs. Cline can emit NDJSON with --json, accepts piped input, and provides --timeout, --cwd, provider, model, and retry options. Those controls let a CI job run from the intended repository directory, stop instead of hanging indefinitely, and pass results to another command. [1][4]

# Structured output suitable for processing
cline --json --cwd "$PWD" --timeout 300 \
  "List TODO comments introduced in this branch. Do not edit files." \
  | jq -r 'select(.type == "agent_event" and .event.text) | .event.text'

# A safe review pattern: give it a diff, request findings only
git diff --merge-base origin/main HEAD \
  | cline --json "Review this patch. Report only concrete bugs, regressions, and missing tests; do not modify files."

Do not silently give a CI agent broad repository write access and expect it to behave like a deterministic linter. Pin the workflow’s permissions, keep secrets out of agent-visible output where possible, limit the task to review or report generation first, and require a human-reviewed pull request for code changes. If approval is required but stdin/stdout is not a TTY, Cline denies required-approval calls rather than waiting for a nonexistent operator—another reason to design CI tasks around inspection unless you have deliberately built a controlled automation path. [4]

How do you resume, debug, and isolate terminal sessions?

Long tasks can be resumed by session ID with --id, while cline history lists saved sessions. Use cline config to inspect active configuration, cline doctor to diagnose local problems, and cline update when you need the CLI’s update mechanism. For experiments that should not share local state with your usual work, --data-dir <path> creates isolated state; --cwd <path> controls the directory in which the agent’s tools operate. [1][4]

cline history
cline --id SESSION_ID "Continue from the previous investigation. Implement only the agreed test case."
cline doctor
cline --cwd ./services/api --data-dir /tmp/cline-api-experiment \
  --auto-approve false "Explain this service's startup path without editing files."

For unattended long-running work, the CLI also offers --zen, which dispatches the task to a background hub and exits. That mode runs with full tool auto-approval and no live terminal interaction, according to the CLI documentation. Reserve it for disposable or tightly controlled workspaces—not the first time you ask an agent to alter an important codebase. [4]

What is the safest everyday Cline CLI workflow?

1. Start in a clean Git branch and understand the baseline: status, focused tests, and current failure state.
2. Ask for a plan first when scope is uncertain or the change touches auth, data, dependencies, infrastructure, or public interfaces.
3. Use a bounded implementation prompt with explicit files, constraints, and verification commands.
4. Keep --auto-approve false until you have inspected the task pattern and trust the workspace boundaries.
5. Review git diff as if a teammate wrote it; then run tests and quality checks independently.
6. Commit a small coherent change, or discard it. Do not preserve a confusing half-finished agent edit merely because the agent spent tokens on it.

This workflow is slower than asking for a one-line code snippet, but it is much faster than recovering from an opaque multi-file change. The terminal is valuable because every command, diff, test result, and follow-up question can stay in the same engineering loop.

Why try Cline for terminal coding work?

Cline describes itself as an open-source coding-agent runtime that works in an editor, terminal, or embedded product. In terminal use, that maps directly to the workflow above: the CLI can plan, inspect a codebase, make coordinated edits, execute commands, and support automation in scripts and CI. Its site also documents model choice across hosted providers, local Ollama or LM Studio runtimes, and OpenAI-compatible endpoints. [3]

For pricing, the product site says developers can use a usage-billed Cline provider, bring their own key or local runtime, or choose ClinePass. ClinePass is listed at $9.99 per month after any promotion period, with a note that additional processing fees may apply; it is positioned for access to included open-weight models without separate provider setup or API-key management. If you want an AI coding agent from your terminal but do not want the harness tied to one model provider, those choices are the practical reason to evaluate it. [3][5]