> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Non-Interactive Mode (One-Shot)

> Learn how to use ChatCLI in scripts, automations, and pipelines through command-line flags and pipe usage.

**ChatCLI** was not designed only for interactive conversations. It can be a powerful tool in your automation scripts, CI/CD pipelines, and shell aliases thanks to its "one-shot" mode.

In this mode, you can ask a single question, get the answer, and exit, all in a single command, making it perfect for integration with other tools.

***

## Using the `-p` or `--prompt` Flags

The most straightforward way to use one-shot mode is with the `-p` or `--prompt` flags. ChatCLI will execute the question, print the AI's response to `stdout`, and exit.

```bash theme={"system"}
chatcli -p "What is the command to list all processes consuming more than 500MB of RAM on Linux?"
```

The output will be only the AI's response, ready to be read or processed by another script.

***

## Integrating with Pipes ( | )

One of the most powerful ways to use one-shot mode is by combining it with other command-line tools through pipes. ChatCLI automatically detects if it is receiving data via `stdin` and uses it as context.

<Tabs>
  <Tab title="Summarize a git diff">
    ```bash theme={"system"}
    git diff | chatcli -p "Based on this diff, generate a commit message suggestion following the Conventional Commits standard."
    ```
  </Tab>

  <Tab title="Analyze logs">
    ```bash theme={"system"}
    cat /var/log/nginx/error.log | chatcli -p "Find the most common error in this log and suggest a possible cause and solution."
    ```
  </Tab>

  <Tab title="Analyze CSV data">
    ```bash theme={"system"}
    cat report.csv | chatcli --provider CLAUDEAI --model claude-sonnet-4-6 -p "Analyze this data and give me 3 key insights."
    ```
  </Tab>

  <Tab title="Slash command in a pipe">
    ```bash theme={"system"}
    git diff | chatcli -p "/review"
    ```

    The pipe body becomes the [slash command's](/features/slash-commands) `$ARGUMENTS` — and a `mode: coder` command can act on it with the full coder engine, mid-pipeline.
  </Tab>
</Tabs>

***

## Available Flags in One-Shot Mode

You can customize the behavior of one-shot mode with the following flags:

| Flag                   | Description                                                                                                                                                                                         |
| :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-p`, `--prompt`       | The main question or instruction for the AI.                                                                                                                                                        |
| `--provider <name>`    | Overrides the default LLM provider (e.g., `OPENAI`, `OPENAI_ASSISTANT`, `CLAUDEAI`, `BEDROCK`, `GOOGLEAI`, `XAI`, `ZAI`, `MINIMAX`, `MOONSHOT`, `STACKSPOT`, `OLLAMA`, `COPILOT`, `GITHUB_MODELS`). |
| `--model <name>`       | Overrides the AI model to use (e.g., `gpt-4o`, `claude-sonnet-4-6`).                                                                                                                                |
| `--timeout <duration>` | Sets a time limit for the request (default: `5m`). E.g., `10s`, `1m`.                                                                                                                               |
| `--max-tokens <num>`   | Overrides the maximum number of tokens in the response.                                                                                                                                             |
| `--no-anim`            | Disables the "Thinking..." animation, ideal for clean output in scripts.                                                                                                                            |
| `--agent-auto-exec`    | In one-shot agent mode, automatically executes the first suggested command if it is deemed safe.                                                                                                    |
| `--realm <name>`       | (StackSpot) Sets the `realm` (tenant) for authentication.                                                                                                                                           |
| `--agent-id <id>`      | (StackSpot) Sets the `Agent ID` to use.                                                                                                                                                             |

***

## Agent Mode in One-Shot

One-shot prompts also resolve [slash-command templates](/features/slash-commands): `chatcli -p "/review-pr 1326 security"` expands the template from `.chatcli/commands` before anything runs. Pipes compose naturally — `git diff | chatcli -p "/review"` feeds the pipe body into the command's `$ARGUMENTS`. Pre-execution lines follow your security policy: interactive approval only when stdin is a real terminal; piped runs resolve through policy rules and fail safe to deny — an explicit `allow` rule (e.g. `{ "pattern": "exec git log", "action": "allow" }` in `~/.chatcli/coder_policy.json`) lets a command's `!` lines run fully unattended, which unlocks cron/CI automations.

You can also invoke Agent Mode non-interactively. This is extremely useful for complex automations.

When using `/agent` or `/run` with the `-p` flag, ChatCLI will ask the AI for an action plan and print it. By default, it will not execute the commands.

<Tabs>
  <Tab title="Plan without execution (default)">
    ```bash theme={"system"}
    chatcli -p "/agent find all *.tmp files in the /tmp directory and delete them."
    ```

    This will display the plan suggested by the AI (e.g., `find /tmp -name "*.tmp" -delete`).
  </Tab>

  <Tab title="With automatic execution">
    To execute the plan automatically, use the `--agent-auto-exec` flag. Execution will only occur if the internal security validator does not detect dangerous commands.

    ```bash theme={"system"}
    chatcli -p "/agent find and delete .tmp files" --agent-auto-exec
    ```

    The AI will generate and, if safe, execute the command to clean up the temporary files.
  </Tab>
</Tabs>

<Warning>Use `--agent-auto-exec` with caution. Although the security validator blocks known dangerous commands, always review the behavior in production environments.</Warning>

***

## Running Tools Directly — `chatcli tool`

Sometimes you want a built-in tool's output, not a model's opinion about it. A plain `-p "@tool ..."` **executes the tool and then sends the result to the LLM** as context — slow, token-expensive, and impractical when the output is large. The `tool` subcommand runs the tool and prints its output, with **no LLM call at all**:

```bash theme={"system"}
# List every tool available to the subcommand
chatcli tool list

# Run a tool with regular flags (argv passes through verbatim)
chatcli tool @docs-flatten --root ./docs --format jsonl --output corpus.jsonl

# Or with a single JSON envelope
chatcli tool docs-flatten '{"root":"./docs","format":"jsonl","output":"corpus.jsonl"}'
```

* **Keyless** — no provider configured, no problem: like the MCP server's direct tools, the subcommand only needs the tool itself.
* **Same exposure policy** — the catalog honors `CHATCLI_MCP_TOOLS` (interactive tools are excluded), exactly like the MCP tool surface.
* **Script-friendly** — output goes to stdout, errors to stderr with exit code 1. Perfect for cron jobs, CI steps and pipes.

<Tip>Use `-p "@tool ..."` when you want the model to *reason about* the tool's output; use `chatcli tool` when you just want the output.</Tip>