Cline CLI Tutorial: Use an Open Source Coding Agent in Terminal

This Cline CLI tutorial shows how to use an open source coding agent in your terminal: install it with npm, authenticate a model provider, enter your repository, and start with an approval-gated task. The safest first command is cline --auto-approve false "inspect this repository, explain its architecture, and suggest the smallest useful improvement", because it lets the agent read, propose, and request permission before it changes files or runs commands.

What Is Cline CLI and What Can It Do in a Terminal?

Cline CLI is the terminal interface for Cline’s coding-agent runtime. It can inspect files, edit a codebase, run shell commands, use configured tools, and work either as an interactive terminal UI or as a one-shot command suitable for scripts. “Open source” here refers to Cline’s Apache-2.0-licensed codebase—not necessarily to the model you choose to run behind it. You can authenticate with Cline’s hosted access paths, bring a provider key, or point the tool at supported local or OpenAI-compatible model endpoints.

The important mental model is that this is an agent, not a text-only chatbot. A normal prompt can lead to a sequence of reads, searches, edits, test runs, and retries. That is useful when the task has feedback loops—such as fixing a failing test—but it also means the working directory, repository state, permissions, and model access are part of the execution environment. Treat each run as you would a new automation with the ability to affect your checkout.

How Do You Install Cline CLI?

Install a supported Node.js release first. Cline’s installation documentation lists Node.js 20+ and recommends Node 22. Then install the CLI globally and confirm that your shell can resolve it:

node --version
npm install -g cline
cline --version
cline --help

If cline is not found after installation, open a new shell before troubleshooting. Then check npm’s global binary directory and whether that directory is on PATH. Avoid reaching for sudo npm install -g: it may make the command work temporarily while creating ownership problems for upgrades later. Node version managers or an npm configuration that installs global packages into your home directory are usually cleaner options.

How Do You Authenticate Cline CLI?

Run the interactive authentication flow from any directory:

cline auth

The setup flow lets you select an access path and model. For a provider-key workflow, Cline supports provider selection and model configuration from the command line as well. Do not paste a production key into shell history if you can avoid it: prefer the interactive setup, an environment variable managed by your shell or secret manager, or a dedicated low-privilege credential for automation. Use cline config afterward to inspect the active configuration.

Before asking an agent to change code, prove the integration with a harmless task. From a repository root, run a one-shot question such as cline "describe this project, its test command, and its likely entry point; do not modify files". A useful response should cite concrete paths and distinguish what it observed from what it inferred. If it guesses, narrow the prompt and ask it to inspect specific files.

How Do You Start an Interactive Cline CLI Session?

Change into the repository you want the agent to work on, create or switch to a disposable Git branch, and launch Cline with no prompt:

git switch -c chore/cline-first-task
cline

This opens the interactive terminal UI. Use it when you want a paired workflow: you state the goal, the agent explores and proposes actions, and you review tool requests as they happen. Interactive sessions are best for ambiguous changes, unfamiliar codebases, and debugging, because you can correct the agent before it accumulates a large diff.

Start with bounded requests that include an outcome and verification step. For example: “Find why the API returns 500 when email is absent. Do not edit yet; explain the root cause and proposed test.” Once the explanation matches your understanding, tell it to implement the smallest fix, add a regression test, and run the relevant test command. This two-phase approach reduces the tendency for an agent to turn a diagnosis into an unsolicited rewrite.

How Do Plan Mode and Approvals Keep a Coding Agent Safe?

Plan mode is the practical answer to “how do I keep it from immediately doing things?” Start a planning-oriented run with -p or --plan, then ask for a sequence of changes, risks, and tests. It is especially useful for migrations, dependency upgrades, refactors, or any task where the correct implementation depends on repository conventions rather than a single file.

cline -p "Plan a migration from the legacy config loader to the new loader. Identify affected files, compatibility risks, rollout steps, and tests. Do not modify files."

For initial use, explicitly set --auto-approve false. Cline’s current CLI documentation notes that autonomous execution can modify files and run commands without further prompts, and advises using a clean branch and reviewing results. Approval is not a security boundary by itself—the agent can still suggest bad changes—but it creates a deliberate review point before commands or writes happen.

• Use a clean branch or worktree for any task that writes files.
• Keep secrets out of prompts, source fixtures, command output, and pasted logs.
• Approve reads and ordinary test commands differently from package installs, database operations, deploys, or destructive shell commands.
• Read the diff and run the project’s own formatter, type-checker, linter, and tests after the agent says it is done.
• Prefer a small task per run. A narrow task is easier to verify, revert, and explain in code review.

How Do You Give Cline Better Context for a Codebase?

A coding agent performs better when the prompt supplies the constraints that experienced teammates would already know. Describe the target behavior, important files or subsystem boundaries, compatibility requirements, the commands that count as verification, and what must not change. “Add rate limiting” is underspecified; “add per-IP rate limiting to the public password-reset route, preserve existing error JSON, use the existing Redis client, add deterministic tests, and do not change internal admin routes” is actionable.

Put durable repository guidance in .clinerules rather than repeating it in every conversation. Cline documents rules as project-specific instructions for coding standards, architecture conventions, deployment procedures, and testing requirements, which the CLI can pick up automatically. Keep rules concrete: name the test command, package manager, generated-file policy, migration process, and prohibited directories. Vague rules such as “write clean code” consume context without resolving decisions.

# .clinerules
- Use pnpm, never npm, for project commands.
- Run `pnpm test` and `pnpm lint` before declaring a task complete.
- Do not edit files under generated/; change their source generator instead.
- Keep public API responses backward compatible unless the task explicitly says otherwise.
- Ask before changing database schemas or CI workflows.

How Do You Run Cline CLI in Scripts and CI/CD?

One-shot mode runs a prompt and exits, which is convenient for repeatable analysis. Add --json when another program needs to consume the result: Cline emits newline-delimited JSON events, including a final run_result. Piping input also activates headless behavior, so a Git diff or generated report can become task context without opening an interactive UI.

# Ask for a review of the current diff
git diff origin/main...HEAD | cline "Review these changes for bugs, regressions, and missing tests"

# Extract a final machine-readable result
cline --json "List TODO comments in this repository" \
  | jq -r 'select(.type == "run_result") | .text'

Do not make a write-capable agent your first CI gate. Begin with read-only jobs: summarize release notes, inspect a diff, identify TODOs, or produce a report for a human. If you later enable unattended edits with --auto-approve true, isolate the job to a non-production checkout, scope credentials tightly, set a timeout, cap the trigger conditions, and make the pipeline publish a diff or pull request for review rather than merging automatically. The CLI can also use hooks for policy enforcement; its documentation specifically notes that shell-command restrictions require a PreToolUse hook rather than a built-in command allow/deny list.

Which Cline CLI Commands Matter Most?

• cline — open an interactive terminal session.
• cline "task" — run a one-shot task in the current directory.
• cline auth — configure provider and model access.
• cline config — inspect current configuration.
• cline doctor — diagnose configuration problems.
• cline history — inspect and manage prior tasks.
• cline mcp — manage MCP servers and external tool integrations.
• cline --json "task" — stream structured output for automation.
• cline --cwd /path/to/repo "task" — run against an explicit repository.
• cline --timeout 600 "task" — impose a runtime limit for a longer task.

What Should You Do When Cline Makes a Bad Change?

Stop treating a failed agent run as a conversation problem and return to engineering controls. Inspect git diff, identify the first incorrect assumption, revert only the affected change if appropriate, and rewrite the task around an observable acceptance criterion. Ask the agent to explain the failure using exact test output or file paths before asking it to try again. Cline supports checkpoints and an /undo workflow in interactive use, but Git remains the most portable audit trail and rollback mechanism.

A model may confidently propose a solution that compiles but violates runtime behavior, security policy, or product intent. Tests are evidence, not proof; passing tests often only prove that existing coverage did not catch the mistake. Your best defense is a tight loop: inspect, plan, edit, test, review. The CLI accelerates that loop most when you remain responsible for deciding what “correct” means.

Why Try Cline for Terminal-Based Coding Work?

If this tutorial’s terminal-first workflow fits your team, Cline is the open-source agent runtime behind the CLI: it is designed to work in an editor, terminal, or embedded product, and its CLI supports both interactive sessions and headless automation. That makes it relevant when you want the same agent concepts—planning, tool use, rules, checkpoints, MCP integrations, and model configuration—to travel between local development and scripted workflows.

Cline’s pricing paths are separate from the open-source code: its documentation describes usage-billed Cline access with free model options, a ClinePass subscription priced at $9.99 per month, and bring-your-own-key access for cloud providers or local runtimes. For engineers who want model choice rather than a fixed single-provider workflow, that combination is worth evaluating—but start with the controlled, approval-gated workflow above before making it part of production automation.