Overview

Loop’s headless mode lets you use the AI agent without the interactive TUI. Pass a prompt via --print and Loop will output the response to stdout, then exit.
This is ideal for:
  • CI/CD pipelines
  • Shell scripts
  • Automated code review
  • Batch processing
  • Integration with other tools

Basic Usage

Combining with Flags

All global flags work with --print:

Scripting Patterns

Pipe Output

Use in Shell Scripts

CI Pipeline Integration

Tracing

A build with --features telemetry records the run as one trace and prints the id on stderr (loop-trace-id: …). Labels:
See Tracing. A default binary does not accept --trace-*. Headless runs need a connected provider. Sign up at console.soket.ai, create an API key, and set SOKET_API_KEY (or OPENROUTER_API_KEY / OPENAI_API_KEY). You can also log in once from the TUI. There is no login wizard when stdout is the answer.

Exit Codes

Limitations

  • No approval prompts. Tools follow toolPermissions. Set ask tools to allow when a script must not wait
  • The session is stored, and --resume <id> continues it
  • The answer is printed when the turn finishes, not streamed token by token
  • An untrusted project (the headless default when trust is ask) does not load .loop/ overlays
For automated workflows that need tool approval control, configure toolPermissions in your settings.json to set defaults. See Permissions.