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.

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.

Summarize a git diff

git diff | chatcli -p "Based on this diff, generate a commit message suggestion following the Conventional Commits standard."

Analyze logs

cat /var/log/nginx/error.log | chatcli -p "Find the most common error in this log and suggest a possible cause and solution."

Analyze CSV data

cat report.csv | chatcli --provider CLAUDEAI --model claude-sonnet-4-6 -p "Analyze this data and give me 3 key insights."

Slash command in a pipe

git diff | chatcli -p "/review"

The pipe body becomes the slash command’s $ARGUMENTS — and a mode: coder command can act on it with the full coder engine, mid-pipeline.

---

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: 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.

Plan without execution (default)

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).

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.

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.

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

---

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:

# 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.

Use -p "@tool ..." when you want the model to reason about the tool’s output; use chatcli tool when you just want the output.