Automation & CI/CD

Kepler supports non-interactive modes for benchmarks, CI/CD pipelines, and batch processing. These modes auto-approve all tool calls and output structured data for machine consumption.

Headless Mode

Headless mode runs Kepler without any interactive prompts. It auto-approves all tool calls and outputs structured JSONL to stdout.

kepler --headless "Fix the TypeScript errors in src/app/"
kepler platform --headless --timeout 300 --model deepseek/deepseek-v4-flash "Refactor"
kepler byok --headless --timeout 300 --model anthropic/claude-sonnet-4-6 "Refactor"

When you pass --model in headless mode, choose the route explicitly:

kepler platform ... uses Kepler-managed credentials and platform credit billing.
kepler byok ... uses your configured provider key. The selected model must be valid for an active BYOK provider on the signed-in account.

Headless model routing fails closed. If you request byok without matching BYOK credentials, Kepler returns a credential setup error instead of silently falling back to the platform route or platform defaults.

How It Works

No REPL — the prompt is provided as a command-line argument or via stdin
Auto-approve — all tools execute without confirmation prompts
JSONL output — structured events are written to stdout line by line
Minimal stderr — only writes to stderr when --verbose is set

Output Events

Headless mode streams events as JSON Lines (JSONL) to stdout:

Event Type	Trigger	Fields
`start`	Session begins	`{ type: "start", instruction, model, timestamp }`
`tool_call`	Tool is invoked	`{ type: "tool_call", tool, input }`
`tool_result`	Tool returns	`{ type: "tool_result", tool, result }`
`content`	Assistant message	`{ type: "content", data: { text } }`
`content_partial`	Streaming text	`{ type: "content_partial", data: { text } }`
`complete`	Session ends	`{ type: "complete", turns, tools, tokens, cost, duration }`
`error`	Error occurred	`{ type: "error", error }`
`timeout`	Timeout reached	`{ type: "timeout", duration }`

Exit Codes

Code	Meaning
`0`	Success — task completed without errors
`1`	Error — check the error event in the output
`2`	Timeout — the session exceeded the time limit

Print Mode

Print mode (--print or -p) is a simpler non-interactive mode that runs a single prompt and prints the response as text.

kepler -p "What is the entry point of this project?"
kepler --print "List all the API routes in src/app/api/"

Output Formats

Control the output format with --output-format:

Format	Description
`text` (default)	Plain text output to stdout
`json`	Single JSON object with the full response
`stream-json`	Streamed JSON objects, one per line

# Get structured JSON output
kepler -p "Summarize src/lib/" --output-format json
 
# Stream tokens as they arrive
kepler -p "Explain this project" --output-format stream-json

Local Mode

Local mode (--local) bypasses the Kepler backend and calls LLM APIs directly. This is useful for:

Offline use — no backend dependency
Benchmarking — measure prompt-cache efficiency
Direct provider access — full control over API calls

# Force local mode with a specific model
kepler --local --model claude-sonnet-4-6 "Add a README"
 
# Local mode with OpenRouter
export OPENROUTER_API_KEY="sk-or-v1-..."
kepler --local --model deepseek/deepseek-chat "Refactor auth"

Requirements

An API key for the provider you want to use
Set via environment variable (OPENROUTER_API_KEY, ANTHROPIC_API_KEY, etc.)
Or configured in the dashboard under Settings → API Keys

Resume Mode

Resume mode (--resume, --continue, or -r) continues a previous session.

# Resume the most recent session
kepler --resume
 
# Resume a specific session by ID
kepler --resume session_abc123

Kepler supports multiple resume strategies for managing context:

Strategy	Behavior
`full`	Send the entire conversation transcript
`summary`	Send only a summary of the previous conversation
`summary+tail-10`	Summary + last 10 messages
`summary+tail-20`	Summary + last 20 messages

The agent automatically selects the best strategy based on the model’s context window and the length of the conversation.

Cache Report

For benchmarking, use --cache-report to write a prompt-cache summary to a JSON file:

kepler --headless --cache-report ./cache-results.json "Refactor auth"

The report contains token counts, cache hit/miss rates, and timing data that can be used to compare model and provider cache efficiency.

CI/CD Integration

GitHub Actions

name: Kepler Review
on: [pull_request]
 
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm i -g @axplusb/kepler
      - run: kepler --headless --timeout 120 "Review the diff for bugs and security issues"
        env:
          KEPLER_TOKEN: ${{ secrets.KEPLER_TOKEN }}

Pre-Commit Hook

#!/bin/sh
# .git/hooks/pre-commit
kepler --headless --timeout 60 "Run lint and fix any auto-fixable issues"

Batch Processing

# Process multiple prompts from a file
while read -r prompt; do
  kepler --headless --timeout 120 "$prompt" > "output-$(date +%s).jsonl"
done < prompts.txt

Commands → CLI Flags — Full list of flags for automation
Approvals & Safety → Freeswim — How auto-approval works
Reference → Exit Codes — All exit code meanings

Skills Getting Good Results