Terminal-native CLI for Google Jules.
Dispatch jobs. Monitor sessions. Handle PRs. Zero web UI required.

Getting Started · Command Reference · Agent Guide · API Notes

Contents

• Overview
• Why Not the Web UI?
• Category Focus
• Setup
• Commands
• For AI Agents
• Architecture
• Docs
• Contributing

Category Focus

• Jules Dispatch = an agent-first CLI — Stable JSON-native interface, zero-touch session management, and PR orchestration are what Jules Dispatch delivers. Built for AI agents and power users who live in the terminal.
• Not Jules Dispatch = a web dashboard, a Jules replacement, or a general-purpose automation tool. It wraps the Jules API — it doesn't reinvent it.

---

Overview

Jules Dispatch is a specialized CLI for Google Jules session and PR workflows. Its workflow commands support --json output — clean, typed, and stable — so AI agents (Claude Code, Codex, Gemini, etc.) can dispatch jobs, monitor sessions, and handle PRs without touching a browser.

# Dispatch a new task to Jules
jules sessions create --repo owner/repo --prompt "Refactor the auth middleware to use JWT"

# Monitor progress (JSON-native for easy parsing)
jules sessions get SESS_ID --json

# List active PRs generated by Jules
jules prs list --repo owner/repo

# Plan review mode — Jules pauses after generating a plan
jules sessions create --repo owner/repo \
  --prompt "Migrate all API routes to the new error handling pattern" \
  --approve-plan

# Review and approve when ready
jules sessions approve SESS_ID

---

Why Not the Web UI?

Capability	Jules Web UI	Jules Dispatch CLI
Dispatch jobs	✓	✓
Agent-readable output	—	✓ Stable JSON on workflow commands
Scriptable / automatable	—	✓ Shell pipelines, CI/CD, agent loops
PR lifecycle management	Manual	✓ List, view, merge from terminal
Session monitoring (polling)	Refresh browser	✓ --json + jq for real-time checks
Offline / batch workflows	—	✓ Queue jobs, check later
Integration with gh CLI	—	✓ Direct PR merge, comment, view

---

Setup

Prerequisites

• Bun v1.0+
• gh CLI authenticated (gh auth login)
• Google Jules account with the GitHub App installed
• Jules API key copied from Settings > API Keys

Installation

git clone https://github.com/AVANT-ICONIC/jules-dispatch-cli.git
cd jules-dispatch-cli
bun install

Configuration

Create a .env file in the project root:

JULES_API_KEY=your_key_here

The CLI reads JULES_API_KEY from the environment and sends it using Jules's documented X-Goog-Api-Key authentication header.

# Verify everything works
bun run src/index.ts sources list --json

---

Commands

Command	Description
jules init	Set up and validate a Jules API-key profile
jules config validate	Verify configuration with a read-only API request
jules profile list / create / show / delete	Manage named profiles
jules sources list	List all repositories connected to Jules
jules sessions create	Start a new coding job with a prompt
jules sessions run	Start a job and poll until completion or action is needed
jules sessions get	Get detailed state and recent activities for a session
jules sessions list	List sessions, filterable by repo and state
jules sessions message	Send a prompt or answer to Jules
jules sessions reply	Alias for sessions message
jules sessions approve	Approve Jules's plan and let it execute
jules sessions activities	Show the activity log for a session
jules sessions outputs	Fetch generated patch and PR outputs
jules sessions archive / unarchive / delete	Manage completed session records
jules prs list	List PRs generated by Jules (cross-references sessions)
jules prs view	View details for a specific PR
jules prs merge	Merge a Jules PR
jules prs comment	Post a comment on a Jules PR

API and PR workflow commands accept --json for machine-readable output. Run jules --help for full usage details, or see the Command Reference.

---

For AI Agents

AI agents should always use the --json flag for workflow commands. This ensures the output is a stable JSON object that can be reliably parsed and acted upon — no human-readable formatting, no ANSI escape codes, no surprises.

# Dispatch a job and capture the session ID
SESSION_ID=$(jules sessions create \
  --repo "owner/repo" \
  --prompt "fix: typo in README" \
  --json | jq -r '.id')

# Poll until complete or action is required
while true; do
  STATE=$(jules sessions get "$SESSION_ID" --json | jq -r '.session.state')
  case "$STATE" in
    COMPLETED|FAILED|AWAITING_PLAN_APPROVAL|AWAITING_USER_FEEDBACK|PAUSED) break ;;
    *) sleep 30 ;;
  esac
done

# Find and merge the PR
jules prs list --repo "owner/repo" --json | jq '.[] | select(.julesSessionId == "'"$SESSION_ID"'")'

See AGENTS.md for the full agent integration guide with polling strategies, error handling, and state machine documentation.

Session States

State	Meaning	Agent Action
QUEUED	Jules accepted the session	Poll again in 30s
IN_PROGRESS	Jules is working	Poll again in 30s
AWAITING_USER_FEEDBACK	Jules has a question	Read activities, send a message
AWAITING_PLAN_APPROVAL	Jules generated a plan	Review and approve
PAUSED	Work is paused	Read activities before continuing
COMPLETED	Jules finished	Check outputs for PR
FAILED	Jules failed	Report to user

---

Architecture

┌──────────────────────────────────────────────────────────┐
│                    Jules Dispatch CLI                     │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────┐ │
│  │  Command Bus │  │  Jules API   │  │  Output Layer  │ │
│  │  (Commander) │  │  Client      │  │  (JSON/Human)  │ │
│  └──────┬───────┘  └──────┬───────┘  └───────┬────────┘ │
│         │                 │                   │          │
│         ▼                 ▼                   ▼          │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────┐ │
│  │  gh Bridge   │  │  Retry/429   │  │  Error Handler │ │
│  │  (PR mgmt)   │  │  Backoff     │  │  (typed errors)│ │
│  └──────────────┘  └──────────────┘  └────────────────┘ │
│                                                          │
│  Jules API (v1alpha) ──► https://jules.googleapis.com    │
└──────────────────────────────────────────────────────────┘

• Command Bus: Commander.js with subcommands, required options, and --json on every route.
• Jules API Client: Typed fetch wrapper with X-Goog-Api-Key auth, flat payload convention, and exponential backoff on 429 rate limits.
• gh Bridge: Swappable shell executor (setExecGh for testing) that wraps gh pr list|view|merge|comment with pre-flight auth checks.
• Output Layer: printJson for agents, printHuman for humans — zero global state, explicit mode per call.

---

Docs

Document	Description
Getting Started	Setup, authentication, first commands
Command Reference	Every command with flags, examples, and JSON output shapes
Agent Guide	How AI agents integrate with Jules Dispatch
Jules API Notes	Reverse-engineered API behavior, gotchas, and conventions

---

Contributing

1. Fork the repo
2. Create your feature branch (git checkout -b feature/your-feature)
3. Write tests, run bun test
4. Commit and push
5. Open a Pull Request

# Run the test suite
bun test

# Build the standalone binary
bun run build

---

Built for agents that need to act with precision.