Jules Planning & Progress API for async coding tasks
Learn more at Jules.
Created by @wryenmeek (github-actionsbot).
Quick Start
1. Install
See Install above.
2. Set Up Credentials
Get your API key from your API provider's developer portal. The key typically looks like a long alphanumeric string.
export JULES_API_KEY="<paste-your-key>"
To persist credentials, pipe the token in: echo "$JULES_API_KEY" | jules-pp-cli auth set-token (there is no positional form, so the key never lands in shell history or ps output). Stored secrets live in credentials.toml under the data directory, not in config.toml.
3. Verify Setup
jules-pp-cli doctor
This checks your configuration and credentials.
4. Try Your First Command
jules-pp-cli sessions list
Unique Features
Beyond mirroring the Jules API, this CLI ships nine hand-coded commands for
running Jules sessions unattended and safely at scale:
sessions create --quota-safe — Check quota before dispatching a new
session and retry on 429/400 with exponential backoff (--max-retries,
default 5) instead of failing the first time a rate limit is hit.sessions create --check-conflicts — Detect other in-flight sessions
against the same repo before dispatching, to avoid two sessions racing on
the same codebase.monitor — Poll one session (--session-id) or all of them, printing
state changes as they happen; add --reconcile to flag sessions that have
gone quiet for more than 30 minutes.checkpoint — Save a session's current state and activity history
under a local label (checkpoint save --session-id <id> --label <name>),
then list or restore it later to see what changed since.archive --stale <duration> — Find sessions with no activity for a
given duration (e.g. 7d) and report them so you can free up quota; use
--dry-run to preview without changing anything.diff-validate --session-id <id> — Inspect a completed session's
artifacts for empty diffs, whitespace-only changes, oversized patches, or a
missing commit message before you act on its output.trigger add --cron <expr> --workflow <name> — Record a cron schedule
paired with a GitHub workflow name so recurring Jules runs are documented
in one place (trigger list, trigger pause).persona record --session-id <id> --outcome <outcome> — Save a
session's prompt and outcome locally under a name, then persona show it
later to reuse a prompt that worked well.compliance check --session-id <id> — Run a session's changes through
named policy checks (code review, security scan, license, dependencies,
secrets) before treating it as ready to merge; compliance list-policies
shows what's available.
All nine are local-first: monitor, archive, diff-validate, and the
sessions create flags call the Jules API; checkpoint, persona, and
trigger store their state in this CLI's local SQLite database and never
send it to Jules.
Usage
Run jules-pp-cli --help for the full command reference and flag list.
Paths & environment variables
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|
config | User-editable settings such as config.toml and saved profiles |
data | Durable local data: credentials.toml, data.db, cookies, browser-session proof files, and other auth sidecars |
state | Runtime state such as persisted queries, jobs, and teach.log |
cache | Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
JULES_CONFIG_DIR, JULES_DATA_DIR, JULES_STATE_DIR, or JULES_CACHE_DIR
--home <dir> for this invocationJULES_HOME for a flat relocated root- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export JULES_HOME=/srv/jules
jules-pp-cli doctor
Under JULES_HOME=/srv/jules, the four dirs resolve to /srv/jules/config, /srv/jules/data, /srv/jules/state, and /srv/jules/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"jules": {
"command": "jules-pp-mcp",
"env": {
"JULES_HOME": "/srv/jules"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as JULES_DATA_DIR overrides an explicit --home for that kind. Use JULES_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting JULES_HOME does not move files back to platform defaults, and doctor cannot find credentials left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. On the first auth write, stored secrets leave config.toml and are consolidated into credentials.toml under the data directory. Run jules-pp-cli doctor --fail-on warn to check path and credential-location warnings in automation.
Commands
sessions
Manage sessions
jules-pp-cli sessions approve-plan - Approve pending planjules-pp-cli sessions create - Create new coding task sessionjules-pp-cli sessions delete - Delete sessionjules-pp-cli sessions get - Get specific sessionjules-pp-cli sessions list - List all sessionsjules-pp-cli sessions send-message - Send message to session
sources
Manage sources
jules-pp-cli sources get - Get specific repositoryjules-pp-cli sources list - List connected repositories
Session safety and lifecycle (unique to this CLI)
jules-pp-cli sessions create --quota-safe - Dispatch with quota checks and exponential backoff on rate limitsjules-pp-cli sessions create --check-conflicts - Detect in-flight sessions on the same repo before dispatchingjules-pp-cli monitor - Poll session state and flag stalled sessions with --reconcilejules-pp-cli checkpoint - Save, list, and restore local snapshots of a session's statejules-pp-cli archive --stale <duration> - Find (and optionally clear) sessions with no recent activityjules-pp-cli diff-validate --session-id <id> - Validate a session's diff before acting on itjules-pp-cli trigger - Record cron + GitHub workflow trigger chainsjules-pp-cli persona - Record and reuse successful session prompts locallyjules-pp-cli compliance check --session-id <id> - Run governance policy checks against a session
Self-learning loop
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
jules-pp-cli recall <query> - Look up cached resources for a query before running discoveryjules-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)jules-pp-cli learnings list - Inspect taught rowsjules-pp-cli learnings forget <query> - Undo a teachjules-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/rejectjules-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate countsjules-pp-cli teach-pattern - Install a query/resource template up frontjules-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set JULES_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of jules-pp-cli opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
jules-pp-cli sessions list
# JSON for scripting and agents
jules-pp-cli sessions list --json
# Filter to specific fields by name
jules-pp-cli sessions list --json --select <field>[,<field>...]
# Dry run — show the request without sending
jules-pp-cli sessions list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
jules-pp-cli sessions list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select <field>[,<field>...] returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and add --ignore-missing to delete retries when a no-op success is acceptable
- Explicit confirmation -
--agent does not imply --yes; pass --yes separately only after the target, arguments, and side effects are clear
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Cookbook
See Unique Features above for sessions create --quota-safe
and --check-conflicts — the two safety flags this CLI adds on top of the
plain create endpoint.
# Dispatch a session
jules-pp-cli sessions create \
--prompt "fix the auth bug" \
--source-context '{"repo":"my-org/my-repo"}'
# Preview a session before dispatching it
jules-pp-cli sessions create --prompt "refactor the DB layer" --dry-run
# List sessions, then inspect one
jules-pp-cli sessions list --json
jules-pp-cli sessions get <sessionId>
# Send a follow-up message to a running session
jules-pp-cli sessions send-message <sessionId> --prompt "also update the tests"
# Approve a plan that's waiting on requirePlanApproval
jules-pp-cli sessions approve-plan <sessionId>
# Poll a specific session and flag it if it goes quiet for 30+ minutes
jules-pp-cli monitor --session-id <sessionId> --reconcile --interval 30s
# Save a checkpoint before a risky follow-up message, then compare later
jules-pp-cli checkpoint --session-id <sessionId> --label before-retry save
jules-pp-cli checkpoint --session-id <sessionId> --label before-retry restore
# Find sessions idle for a week (dry run first)
jules-pp-cli archive --stale 7d --dry-run
jules-pp-cli archive --stale 7d --yes
# Validate a completed session's diff before merging its output
jules-pp-cli diff-validate --session-id <sessionId> --strict
# Run compliance checks before treating a session as mergeable
jules-pp-cli compliance check --session-id <sessionId>
jules-pp-cli compliance list-policies
# Record a prompt that worked well, and reuse it later
jules-pp-cli persona record --name refactor-pattern --session-id <sessionId> --outcome success
jules-pp-cli persona --name refactor-pattern --json show
# Sync sessions/sources into the local store, then query them offline
jules-pp-cli sync
jules-pp-cli search "auth bug" --json
# Ask the CLI which command matches a capability you have in mind
jules-pp-cli which "detect stalled sessions"
Health Check
jules-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Run jules-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/jules-pp-cli/config.toml; --home, JULES_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
JULES_API_KEY | per_call | Yes | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, jules-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
jules-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $JULES_API_KEY
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
Generated by CLI Printing Press