# Cline CLI Guide: Running the Autonomous Coding Agent in Your Terminal

Cline CLI brings autonomous coding loops out of the graphical editor and directly into shell sessions, scripts, and CI/CD pipelines. This guide explains how to install the global npm package, configure AI providers, pipe context through standard input, and run headless agent tasks without manual confirmation prompts. Connecting Cline to shared cloud workspaces ensures that multi-agent teams keep file changes, context, and version history synchronized across machines.

Source: https://fast.io/resources/cline-cli-guide/
Last reviewed: 2026-09-05

## Why Run Cline in the Terminal Instead of the IDE?

Running an autonomous coding agent exclusively inside an editor extension confines software automation to a single developer workstation. When an agent must analyze pull requests in a continuous integration pipeline, run scheduled codebase audits on remote servers, or chain shell commands across local repositories, graphical desktop interfaces become an operational roadblock. Autonomous software engineering requires an agent runtime that executes directly within terminal emulators, shell scripts, and headless build runners.

Cline CLI is a standalone terminal interface and headless runner for the Cline autonomous coding agent, enabling developers to run agent loops directly from command line sessions and CI/CD pipelines. It decouples the core agentic reasoning engine from the Visual Studio Code graphical window while maintaining parity with the extension's tool architecture, system prompts, and configuration formats.

```
+-------------------------------------------------------------------+
|                            Cline Core                             |
|      (Task Execution, File System Tools, MCP Client, Reasoning)   |
+---------------------------------+---------------------------------+
                                  |
         +------------------------+------------------------+
         |                                                 |
         v                                                 v
+-------------------------------+         +-------------------------------+
|     IDE Extension Engine      |         |       Cline Terminal CLI      |
|  - Graphical Diff Viewers     |         |  - Interactive TUI (-i)       |
|  - Editor Sidebar Integration |         |  - Headless CI/CD (--json)    |
|  - Manual Click Approvals     |         |  - Stdin/Stdout Shell Pipes   |
|  - Desktop Machine Bound      |         |  - Scriptable Auto-Approvals  |
+-------------------------------+         +-------------------------------+
```

The terminal interface solves three distinct engineering bottlenecks:

1. **Remote and Headless Environments.** Running agents on headless Linux virtual machines, SSH jump hosts, and Docker containers previously required running headless VS Code server instances or mock display servers. Cline CLI executes natively in any POSIX-compliant shell without graphical dependencies.
2. **Deterministic Scripting and Piping.** Standard command line utilities communicate through text streams. Cline CLI accepts piped input from `git diff`, log files, and build outputs, allowing developers to integrate agent evaluations into existing shell scripts and automation pipelines.
3. **Continuous Integration Automation.** By accepting headless execution flags and non-interactive auto-approvals, the CLI allows CI/CD systems like GitHub Actions and GitLab CI to dispatch agent tasks on pull requests, diagnose broken test suites, and format code changes without human intervention.

| Dimension | IDE Extension Interface | Terminal Command Line Interface |
| :--- | :--- | :--- |
| **Primary Environment** | Visual Studio Code, Cursor, Windsurf | Shell terminals (Bash, Zsh, Fish), CI/CD runners |
| **Interaction Style** | Graphical side panel, visual diff inspection | Interactive terminal UI, command-line flags, JSON streams |
| **Pipeline Automation** | Manual triggers inside an active desktop window | Headless shell piping (`cat`, `git diff`, Unix pipes) |
| **Approval Mechanics** | Point-and-click UI approval prompts | Keyboard interactive prompts or `--auto-approve true` |
| **Execution Context** | Local developer laptop or remote desktop session | Local laptops, remote SSH hosts, cloud containers |
| **MCP Toolset** | Configured via extension graphical settings | Configured via `cline mcp` or `~/.cline/mcp.json` |

While the graphical extension remains ideal for interactive pair programming where visual diffing is helpful, the command line interface gives developers a scriptable runtime suited for repeatable engineering operations.

## How to Install and Authenticate the Cline Command Line Interface

Getting started with Cline in your terminal requires Node.js 20 or higher, with Node.js 22 recommended for long-term stability. The CLI distributes as a standard package through npm and runs across macOS, Linux, and Windows through WSL (Windows Subsystem for Linux).

Follow these four steps to install, configure, and verify the CLI:

1. **Install the CLI package globally.** Install the executable using npm:

```bash
npm install -g cline
```

2. **Authenticate your AI provider.** Run the interactive authentication command to configure your inference backend:

```bash
cline auth
```

3. **Launch an interactive test session.** Start the terminal user interface to verify your setup:

```bash
cline
```

4. **Pipe a test command.** Confirm headless execution by piping a prompt through standard input:

```bash
echo "explain what this repository does" | cline
```

### Provider Configuration and Credentials

The `cline auth` command opens a menu in your terminal that lets you select your model provider and enter the necessary credentials. The CLI supports identical providers to the IDE extension:

- **Anthropic:** Connect directly to Claude models using an Anthropic API key or an active Claude Code subscription.
- **OpenAI and Compatible Gateways:** Configure OpenAI API keys, Codex endpoints, or third-party gateways that implement the OpenAI chat completions schema.
- **Google Gemini:** Supply a Gemini API key for high-speed frontier model inference.
- **AWS Bedrock and Cloud Platforms:** Configure AWS IAM access keys, CLI profiles, or Bedrock API keys for enterprise environments.
- **Local Runtimes:** Connect to local instances running Ollama, LM Studio, or vLLM to run coding agents entirely on local hardware without sending code to external APIs.
- **OpenRouter and ClinePass:** Access multi-model routing or ClinePass subscriptions for discounted inference on popular open coding models.

You can also override credentials or models for a single command invocation without modifying global configuration files:

```bash
cline -P anthropic -m claude-3-7-sonnet-20250219 -k your_api_key_here "audit package.json dependencies"
```

### Local Storage Locations and Settings

The Cline CLI stores its operational data in your user directory. Understanding where these files live helps you maintain configuration portability across workstations:

- `~/.cline/`: The primary data directory containing task session logs, cached context, and operational state.
- `~/.cline/data/settings/`: Contains provider credentials, default model preferences, and custom instructions.
- `~/.cline/mcp.json`: The Model Context Protocol configuration file defining local and remote tool servers.

When testing new agent configurations or running isolated builds in shared environments, specify a dedicated state directory using the `--data-dir` flag:

```bash
cline --data-dir /tmp/cline-sandbox "generate OpenAPI client definitions"
```

This isolates session history and temporary cache files from your primary user profile, ensuring clean test runs in shared development environments.

## How to Run Interactive Sessions and Headless Commands

The Cline CLI provides two operational modes: an interactive terminal user interface (TUI) designed for conversational developer workflows, and a headless mode built for automation scripts and background tasks.

### Running Interactive Terminal Sessions

To start an interactive session, run `cline` without arguments or pass the `-i` flag to launch the terminal user interface:

```bash
cline -i
```

In interactive mode, Cline renders a terminal layout displaying conversation history, current task status, token consumption, and proposed tool actions. When the agent decides to read a file, execute a shell command, or write code, it pauses and prompts you for approval:

```text
Cline: I propose executing the following shell command:
$ npm test -- tests/auth.test.ts

Approve execution? (y/n/always):
```

You can approve the single step, reject it with corrective feedback, or grant approval for that tool type for the remainder of the session. You can also reference files directly in your prompts using the `@` syntax:

```bash
cline -i "Review the architecture documented in @./docs/architecture.md and suggest refactoring steps"
```

### Headless Execution Mechanics

When running automation tasks, headless mode in Cline activates automatically when using the JSON flag, redirecting standard output, or piping standard input into the command. In headless mode, the interactive TUI is suppressed, allowing scripts to process the raw output or pipe messages directly into downstream logging tools.

The CLI decides whether to run interactively or headlessly based on standard shell stream detection:

- **Stdin Piped:** Executing `cat query.txt | cline` runs headlessly because standard input is attached to a stream rather than an interactive terminal.
- **Stdout Redirected:** Executing `cline "format code" > output.log` disables terminal control sequences to keep log files readable.
- **JSON Output Requested:** Passing `--json` outputs newline-delimited JSON objects that can be parsed programmatically.

To run an automated bug review using standard input piping:

```bash
git diff HEAD~1 | cline "identify potential null pointer exceptions in these changes"
```

To capture plain-text task execution directly to disk:

```bash
cline "write comprehensive JSDoc comments for src/parser.ts" > codegen.log
```

### Unattended Autonomous Execution

When running unattended tasks, Cline pauses by default for human confirmation before modifying files or running shell commands. In continuous integration environments and automated cron tasks, no human is present to approve these actions. To allow the agent to run autonomously from start to finish, supply the `--auto-approve true` flag:

```bash
cline --auto-approve true "run npm run lint --fix and commit the resolved changes"
```

When `--auto-approve true` is set, Cline executes read operations, write operations, and permitted shell commands automatically until the goal is achieved or a fatal error occurs.

### Planning Versus Acting Modes

To separate thinking from implementation, Cline separates task execution into two operating phases:

- **Plan Mode (`-p, --plan`):** Directs the agent to analyze requirements, inspect existing files, and design an implementation roadmap without making file modifications or running state-altering commands.
- **Act Mode (Default):** Grants the agent full execution permissions to write code, install packages, and run tests.

To formulate an implementation strategy first:

```bash
cline -p "design a migration plan from CommonJS to ES modules"
```

To execute the approved migration directly:

```bash
cline --auto-approve true "convert src/index.js to an ES module using import syntax"
```

### Execution Controls and Guardrails

To prevent autonomous coding loops from running indefinitely or consuming excess API tokens on stuck tasks, configure strict runtime boundaries:

- **Reasoning Effort (`--thinking <level>`):** Sets model reasoning depth between `none`, `low`, `medium`, `high`, and `xhigh` (default is `medium`). Use `low` for fast syntactical transformations and `high` for complex algorithmic refactoring.
- **Task Timeout (`-t, --timeout <seconds>`):** Enforces a hard execution ceiling. For example, `--timeout 300` halts the agent if execution exceeds five minutes.
- **Retry Caps (`--retries <count>`):** Limits consecutive tool failures before halting execution, preventing the agent from retrying failing commands in an endless loop.

## Steps to Automate CI/CD Workflows and Shell Pipelines

The primary strength of the Cline CLI is its ability to participate in Unix-style pipelines and continuous integration jobs. By treating code generation and auditing as command line filters, teams can embed intelligent agent evaluations into daily build workflows.

### Piping Context and Chaining Agent Tasks

When working in the shell, developers frequently need to pass dynamic system context into an agent without manually copying and pasting terminal output. You can pipe any command output directly into Cline.

To summarize the latest git commit diff:

```bash
git show HEAD | cline "write a concise release note bullet point"
```

To diagnose a failed test output:

```bash
npm test 2>&1 | cline "analyze the stack trace and propose a patch for the failing test"
```

You can also chain multiple Cline agent runs together, using one agent invocation to produce code and a subsequent invocation to audit or document the output:

```bash
git diff origin/main | cline "explain these changes in technical detail" | cline "generate a pull request description markdown template"
```

### Streaming Structured JSON Output

When integrating Cline into automation dashboards or custom webhook dispatchers, terminal styling codes and progress bars interfere with machine parsing. Adding the `--json` flag causes the CLI to output newline-delimited JSON (NDJSON) messages:

```bash
cline --json --auto-approve true "check for unused dependencies in package.json"
```

Each line emitted by the process corresponds to a structured JSON payload:

```json
{"type":"say","text":"Analyzing package.json dependencies...","ts":1760501486669,"say":"text"}
{"type":"say","text":"Found 2 unreferenced packages: lodash, rimraf","ts":1760501491204,"say":"text"}
```

Key attributes in the JSON streaming schema include:

- `type`: Indicates whether the message is an agent utterance (`say`) or an interactive question/approval request (`ask`).
- `text`: The human-readable string payload containing the reasoning or response text.
- `ts`: A Unix timestamp in milliseconds indicating when the event occurred.
- `say` or `ask`: Specific subtypes classifying the action, such as tool calls, command executions, or text replies.
- `partial`: A boolean indicating whether the message is a streaming text chunk or a completed block.

You can pipe this output directly into utilities like `jq` to extract specific results for downstream automation:

```bash
cline --json "list all deprecated methods in src/api.ts" | jq -r 'select(.say == "text") | .text'
```

### Restricting Shell Command Execution

When running autonomous agents with `--auto-approve true`, security is a fundamental concern. An unconstrained agent could accidentally run destructive shell commands. The CLI allows administrators to restrict permitted command patterns using the `CLINE_COMMAND_PERMISSIONS` environment variable:

```bash
export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm test*", "npm run build*", "git status", "git diff"], "deny": ["rm -rf *", "sudo *", "curl *", "wget *"]}'
```

If the agent attempts to execute a command matching a denied pattern or outside the allowed scope, execution is blocked and the agent is informed of the constraint.

### GitHub Actions Integration

To automate pull request reviews and bug triage in GitHub Actions, configure a standard runner environment with Node.js installed. The following workflow runs Cline on pull requests to verify code quality:

```yaml
name: Autonomous Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Cline CLI
        run: npm install -g cline
      - name: Run Headless Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git diff origin/${{ github.base_ref }}...HEAD > diff.txt
          cat diff.txt | cline -P anthropic -m claude-3-7-sonnet-20250219 --timeout 600 --auto-approve true "Perform a strict code review of this diff. Flag any security vulnerabilities, memory leaks, or unhandled exceptions." > review.md
      - name: Post PR Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: review
            });
```

This pipeline extracts the pull request diff, feeds it into Cline CLI running on Node.js 22, and posts the resulting analysis directly back to the pull request discussion thread.

## Connecting Cline CLI to Persistent Remote Workspace Storage

While running Cline CLI in terminal scripts and CI/CD pipelines enables rapid automation, it introduces a storage challenge: state isolation. Ephemeral CI runners, container instances, and developer laptops discard local context once tasks finish. When an agent creates documentation, generates OpenAPI specs, or audits codebase architectures, those output artifacts remain locked on a single machine or vanish when the CI container tears down.

Traditional commodity cloud storage tools like Google Drive, Dropbox, and Box are designed for human file synchronization rather than agentic tool calling. They lack native Model Context Protocol support, require custom webhook middleware to notify downstream agents of changes, and lack integrated semantic retrieval across multi-agent sessions.

Connecting Cline CLI to a centralized workspace platform like Fastio bridges this gap. Fastio provides persistent, team-owned workspaces where humans and autonomous agents collaborate using the same files, notes, and activity records.

```
+-------------------------------------------------------------------+
|                        Autonomous Agent                           |
|                    Cline CLI (Terminal / CI)                      |
+---------------------------------+---------------------------------+
                                  |
                                  | MCP over Streamable HTTP
                                  v
+-------------------------------------------------------------------+
|                     Fast.io Intelligent Cloud                     |
|  - Per-File Version History (Every write auditable and rollback-ready)
|  - Built-in RAG Intelligence Mode (Semantic retrieval + exact match)
|  - Scoped Granular Permissions (Org / Workspace / Folder / File) |
|  - Collaborative Notes & Metadata Views (Document data extraction)|
+---------------------------------+---------------------------------+
                                  |
         +------------------------+------------------------+
         |                                                 |
         v                                                 v
+-------------------------------+         +-------------------------------+
|       Engineering Team        |         |       Downstream Agents       |
|  - Human Review & Audit Logs  |         |  - Claude Code / OpenClaw     |
|  - Branded Client Shares      |         |  - Verification & Build Bots  |
+-------------------------------+         +-------------------------------+
```

### Configuring Remote MCP Storage in the CLI

The Cline CLI natively supports external tool extension through the Model Context Protocol. MCP servers are configured in `~/.cline/mcp.json` or managed interactively via the built-in wizard:

```bash
cline mcp
```

The `cline mcp` wizard allows you to list existing servers, add new connections, edit server properties, and toggle servers on or off.

To connect your CLI agent to Fastio, edit `~/.cline/mcp.json` and configure Fastio's remote endpoint using Streamable HTTP. Streamable HTTP maintains a persistent bidirectional channel that operates smoothly across modern networks:

```json
{
  "mcpServers": {
    "fastio-workspace": {
      "type": "streamableHttp",
      "url": "https://mcp.fast.io/mcp",
      "headers": {
        "Authorization": "Bearer your_fastio_api_token_here"
      },
      "disabled": false,
      "autoApprove": [
        "storage_list",
        "storage_read",
        "storage_write"
      ]
    }
  }
}
```

Replace `your_fastio_api_token_here` with a valid developer key created in the Fastio web console. By specifying tool names in the `autoApprove` array, you allow Cline CLI to interact with workspace storage during autonomous runs without prompting for manual confirmation.

### Architectural Benefits of Shared Cloud Workspaces

When teams route agent output to a persistent cloud workspace, they gain critical operational capabilities:

1. **Per-File Version History.** Every time Cline CLI writes an updated file or replaces a document, Fastio captures a distinct file version. If an automated script introduces an unexpected change during an unattended run, engineers can inspect the version history and restore earlier versions with complete auditability.
2. **Intelligence Mode and Semantic Search.** Fastio automatically indexes workspace files for semantic search and Retrieval-Augmented Generation (RAG). When Cline CLI runs subsequent tasks, it can query the workspace using natural language queries with citations, pulling in only relevant document snippets rather than loading entire repositories into its context window.
3. **Multi-Agent Coordination and Handoffs.** Multiple autonomous agents (such as Cline CLI in terminal sessions and Claude Code or custom agents on other machines) can read and write to the same workspace folders. Fastio functions as neutral ground where agents post outputs, update Collaborative Notes, and hand finished work over to human engineers.
4. **Structured Document Extraction.** With [Metadata Views](/product/document-data-extraction/), workspaces turn unstructured files like technical specifications, audit logs, and benchmark reports into typed, queryable spreadsheet views that agents and humans can filter without custom OCR pipelines.

To learn more about structuring storage for autonomous software agents, explore the [Storage for AI Agents](/storage-for-agents/) overview and review [Fastio Pricing](/pricing/).

Fastio operates on an organization-first subscription model. Every organization starts with a 14-day free trial, which requires a credit card. | Plans are Starter at $29/mo, Business at $99/mo, and Growth at $299/mo. An autonomous agent can sign up free, build workspace directories and shares, and transfer ownership to a human team member who joins and activates the subscription.

## Frequently asked questions

### How do I install Cline CLI?

Install Cline CLI globally through npm by running npm install -g cline on a machine with Node.js 20 or higher installed. Once the package finishes installing, run cline auth to set up your AI model provider and credentials, then execute cline to start an interactive session or pass a prompt directly.

### Can I run Cline without VS Code?

Yes, Cline CLI runs as a standalone command line binary that operates completely independently of Visual Studio Code. It executes within terminal emulators on macOS, Linux, and Windows WSL, as well as in headless cloud servers, Docker containers, and CI/CD pipelines without graphical dependencies.

### Does Cline CLI support headless execution in CI/CD?

Yes, Cline CLI automatically activates headless mode when standard input is piped, when standard output is redirected to a file, or when the --json flag is passed. Adding the --auto-approve true flag enables fully autonomous, unattended execution suited for continuous integration runners.

### How do I configure MCP servers in the Cline CLI?

You can configure Model Context Protocol servers in the CLI by launching the interactive wizard with cline mcp, or by directly editing the ~/.cline/mcp.json configuration file. The CLI supports local STDIO servers using command and argument parameters, as well as remote hosted servers using Streamable HTTP endpoints and authorization headers.

### Where does Cline CLI store its configuration and session data?

Cline CLI stores its operational data in your user home directory under ~/.cline. Configuration files and provider credentials reside in ~/.cline/data/settings, while MCP server configurations live in ~/.cline/mcp.json. You can override the default state path using the --data-dir flag.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.