Using the CLI with Agents & AI

The Reepl CLI is built to be driven by more than just a person typing. Scripts, automation tools, and AI agents can all use it — and this page covers everything you'll want if that's your goal. It's a bit more technical than the rest of the CLI docs, by design.

Everything below is a stable promise you can build on: it won't change out from under you.

Clean, predictable output

Every command returns a single, tidy JSON object, so your code never has to read sentences meant for humans.

When it works:

{ "ok": true, "data": { /* the result */ } }

When something goes wrong:

{ "ok": false, "error": { "code": "PLAN_REQUIRED", "message": "…", "status": 403 } }

A few things to rely on:

• You get JSON automatically whenever the output isn't going to a live terminal (for example, when a script captures it). You can also force it with --json, or force the human-readable version with --no-json.
• Don't read the wording — just check ok, and look at error.code when it's false. The wording can change; the codes won't.

Error codes you can branch on

Each type of failure also sets a distinct exit code, so a script can react without parsing anything at all.

Exit code	Meaning	Example error.code values
0	Success	—
1	General API error	API_ERROR
2	Network problem	NETWORK
4	Not signed in / config issue	UNAUTHENTICATED, REFRESH_TOKEN_INVALID, CONFIG
5	Plan required	PLAN_REQUIRED, PREMIUM_REQUIRED
6	An integration needs reconnecting	RECONNECT_REQUIRED, MISSING_DM_SCOPES, GEMINI_NOT_LINKED
7	Rate limited	RATE_LIMITED
8	Not found	NOT_FOUND
9	Bad input	VALIDATION, VERSION_CONFLICT

So if your agent sees exit code 5 with PREMIUM_REQUIRED, it knows to stop and tell the user rather than retry.

Let the CLI describe itself

Instead of scraping help text, ask the CLI for its full list of commands and options as JSON:

reepl schema

This is generated from the CLI itself, so it always matches exactly what the tool accepts — perfect for building an agent's tool definitions or validating input before you run anything.

Signing in without a browser

reepl login normally opens a browser, which doesn't work in an automated environment. Instead, pass your tokens directly:

reepl login --token "$REEPL_ID_TOKEN" --refresh "$REEPL_REFRESH_TOKEN"

Tip: set REEPL_CONFIG_DIR to a separate folder for each job or agent run, so parallel runs keep their own independent sessions and never clash. See Signing In for more.

Passing text in

You've got a few options for content:

• Post, comment, or reply text: use -c/--content or -t/--text, read from a file with --file <path>, or pipe it in (echo "..." | reepl post create -c -).
• Carousel slides: use --slides '<json>' or --slides-file <path>.

Safety built in for automated use

• Drafts by default — an agent that only calls post create will never post anything publicly without a deliberate publish or schedule flag.
• No surprise Reddit posts — reepl reddit can only search and reply, never create new posts.
• Clear plan gates — actions like reddit search, style train, dm, and x reply return a clean PLAN_REQUIRED or PREMIUM_REQUIRED code, so your agent can check first instead of retrying a request that can't succeed.

A simple example

Here's a small script that creates a draft and reacts sensibly to whatever comes back:

#!/usr/bin/env bash
# Create a draft and handle the result cleanly.
out=$(reepl post create -c "Draft from my automation." --json)
code=$?

if [ "$code" -eq 0 ]; then
  id=$(echo "$out" | jq -r '.data.id')
  echo "Draft created: $id"
elif [ "$code" -eq 5 ]; then
  echo "This needs a paid plan — stopping." >&2
  exit 5
elif [ "$code" -eq 4 ]; then
  echo "Not signed in — run reepl login." >&2
  exit 4
else
  echo "$out" | jq -r '.error.message' >&2
  exit "$code"
fi

Related