Automation & CI/CD

Bahulam 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 Bahulam without any interactive prompts. It auto-approves all tool calls and outputs structured JSONL to stdout.

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

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

• bahulam platform ... uses Bahulam-managed credentials and platform credit billing.
• bahulam 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, Bahulam returns a credential setup error instead of silently falling back to the platform route or platform defaults.

How It Works

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

Runtime Modes

Bahulam has four explicit runtime modes. The prompt, history, message events, tool schemas, tool results, and JSONL output use the same contract in every mode; the mode selects who owns the agent loop and where the model request is sent.

Examples:

bahulam --remote -p "Review the authentication flow"
bahulam --bundled -p "Run the local compatibility runtime"
bahulam --local -p "Refactor the authentication flow"
bahulam --direct -p "Explain this module"

--local requires a Bahulam login because the gateway authenticates the session and applies the selected Bahulam route. --direct requires ANTHROPIC_API_KEY or OPENROUTER_API_KEY and bypasses both the backend and the Bahulam Gateway. The mode flags are mutually exclusive.

The mode flags apply to both one-shot/headless execution and the interactive REPL. A session started with bahulam --local, bahulam --bundled, or bahulam --direct keeps that runtime mode for every interactive turn.

Plugins in the four modes

Plugin discovery and local tool execution are shared. A plugin’s handlers, MCP clients, state tools, and workspace integrations run in the npm process in all four modes.

• In --remote and --bundled, npm advertises plugin agent and tool schemas to the runtime (client_agents, client_agent_tools, and client_tools). The runtime may plan or delegate, but a plugin tool call returns to npm for execution; plugin code is never executed by the backend.
• In --local and --direct, npm owns planning, delegation, approvals, and plugin tool calls. Only the model transport changes: gateway for --local, provider SDKs for --direct.

This means a plugin should not need separate tool implementations for the four modes. Its schemas, handlers, agent prompts, tool allowlists, and state contract are shared.

Output Events

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

Exit Codes

Print Mode

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

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

Output Formats

Control the output format with --output-format:

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

Bundled Local Runtime

Bundled mode (--bundled) runs the backend-compatible agent runtime bundled inside the npm package instead of sending the turn to the cloud backend. Model calls still go through Bahulam Gateway, so platform billing, BYOK routing, cache reporting, and traces use the same gateway path.

This is useful for:

• Backend-independent execution — no cloud backend dependency for the agent loop
• Benchmarking — measure prompt-cache efficiency
• Local tool execution — file, shell, skill, MCP, and sub-agent tools run from the local machine

# Force local mode with a specific model
bahulam --bundled --model claude-sonnet-4-6 "Add a README"
 
# Bundled mode with BYOK routing through Bahulam Gateway
bahulam --bundled --model deepseek/deepseek-chat "Refactor auth"

Requirements

• A valid Bahulam login token
• Bahulam Gateway access for the selected route
• BYOK provider credentials configured in Settings → API Keys when using bahulam byok
• The bundled runtime package for your platform

For npm-owned orchestration through the gateway, use --local. For a direct provider connection with no gateway, use --direct.

Resume Mode

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

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

Bahulam supports multiple resume strategies for managing context:

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:

bahulam --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: Bahulam 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 @bahulam/code
      - run: bahulam --headless --timeout 120 "Review the diff for bugs and security issues"
        env:
          BAHULAM_TOKEN: ${{ secrets.BAHULAM_TOKEN }}

Pre-Commit Hook

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

Batch Processing

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

Related

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