CLI

The Rankhog CLI calls the public REST API. It is designed for humans and AI agents.

Configure

export RANKHOG_API_BASE_URL="https://api.rankhog.com"
export RANKHOG_OUTPUT="json"

Agents should prefer --json or RANKHOG_OUTPUT=json.

Sign In

The CLI uses Better Auth device authorization.

rankhog login

For non-interactive agents, print the code without polling:

rankhog --json login --no-poll --no-open

You can also provide a bearer token directly:

export RANKHOG_ACCESS_TOKEN="..."

Device tokens are stored in the CLI YAML config with file mode 0600. RANKHOG_ACCESS_TOKEN always takes precedence for ephemeral agent runs.

Find Workspace IDs

rankhog --json workspaces list

Set defaults for scripts:

export RANKHOG_ORGANIZATION_ID="org_..."
export RANKHOG_WEBSITE_ID="web_..."
export RANKHOG_MANAGED_REDDIT_ACCOUNT_ID="acct_..."

Common Commands

rankhog --json reddit rules SaaS
rankhog --json reddit activity SaaS --max-posts 25 --max-comments 25
rankhog --json strategy radar coverage
rankhog --json reddit actions status job_...
rankhog --json browser status
rankhog --json opportunities list
rankhog --json opportunities get opp_...
rankhog --json strategy show
rankhog --json strategy discovery start --direction "Find comparison demand" --idempotency-key start-001
rankhog --json strategy discovery run --idempotency-key run-001
rankhog --json strategy discovery stop --idempotency-key stop-001
rankhog --json strategy radar disable --idempotency-key radar-off-001
rankhog --json analytics summary --period week
rankhog --json jobs planned --organization-id "$RANKHOG_ORGANIZATION_ID"
rankhog --json credits balance
rankhog --json credits ledger --limit 50

Opportunities

List the workspace's actionable opportunities:

rankhog --json opportunities list --limit 50

Include --no-recent to omit completed and dismissed results from the previous 14 days. Inspect one opportunity with its public-safe evidence, blocker remediation, timing, and linked action summary:

rankhog --json opportunities get opp_...

Opportunity responses keep the existing evidence field and add a compact evidenceSummary when available. New clients may use optional timeZone and nextTransitionAt values for scheduling. Treat missing values as null; these read fields do not grant approval or execution permission.

Opportunity reads require rankhog:read. Approval, strategy changes, dismissal, draft editing, warm-up, billing, and account selection remain human-authenticated product actions.

Radar Coverage

Inspect source freshness, post/comment overlap, backlog, and eligible collector capacity without triggering an ad hoc Reddit fetch:

rankhog --json strategy radar coverage

The command requires rankhog:read. Radar and Discovery controls require a human CLI-device actor, strategy:write, idempotency, and rate limits.

Credits

Credits pay for warm-ups, posts, comments, and replies. Read the balance for the default product:

rankhog --json credits balance

The response includes this product's period credits, the organization bank, committed credits held by queued actions, spendable credits, every product's balance under products, and the current costs table. Read the organization as a whole with --org-wide, or pick a product with --website-id:

rankhog --json credits balance --org-wide
rankhog --json credits balance --website-id web_...

Page through the ledger, newest first. Every grant, purchase, refund, adjustment, and debit is one row with its actorKind and the action, warm-up, purchase, or opportunity it paid for:

rankhog --json credits ledger --limit 50
rankhog --json credits ledger --cursor "..." --limit 50

Pass nextCursor from the previous page as --cursor. nextCursor is null on the last page.

Both commands need only organization membership, so they work on lapsed and locked workspaces. credits balance requires rankhog:read; credits ledger also requires credits:read. The ledger never includes member names or user ids. Buying credit packs, auto top-up, and admin adjustments are billing changes and stay in the Rankhog app.

Reddit Actions

Use reddit actions to store, execute, and poll real Reddit writes through Rankhog Desktop. Supported action types are post, comment, reply, upvote, and join_subreddit.

Create a comment action:

rankhog --json reddit actions create \
  --type comment \
  --target-url "https://www.reddit.com/r/SaaS/comments/examplepost/example/" \
  --body "We saw better activation after asking users for one setup action instead of showing a long checklist." \
  --risk-summary "Contextual reply with no link and no promotional claim." \
  --idempotency-key "action-comment-2026-06-17-001"

Create a post with flair:

rankhog --json reddit actions create \
  --type post \
  --subreddit SaaS \
  --title "What actually improved your SaaS activation?" \
  --body-file ./reddit-post.md \
  --flair "Discussion" \
  --risk-summary "Discussion prompt, no link, and relevant to SaaS operators." \
  --idempotency-key "action-post-2026-06-17-001"

Execute an authorized action. The response means the work is queued.

rankhog --json reddit actions execute act_... \
  --acknowledge \
  --idempotency-key "execute-action-2026-06-17-001"

Queued response:

{
  "status": "queued",
  "executionId": "job_...",
  "jobId": "job_...",
  "plannedRedditActionId": "act_...",
  "statusUrl": "/agent/v1/reddit-action-executions/status?executionId=job_..."
}

Poll status:

rankhog --json reddit actions status job_...

Possible statuses:

queued
running
succeeded
failed
blocked
cancelled
verification_required

verification_required means Reddit may have accepted the final submit, but Rankhog could not prove it. Do not blindly execute the same planned action again.

Duplicate execute calls with the same planned action and idempotency key return the existing execution instead of posting twice.

When the product cannot spend the action's cost, execute fails with 402 agentic_insufficient_credits and reports required, available, and spendable. Check credits balance first.

Pass --executor-reddit-account-id ra_... to request a specific ready, product-granted Reddit account. Omit it to let Rankhog choose.

List every execution receipt for the current workspace:

rankhog --json reddit actions history \
  --origin warmup \
  --status submitted \
  --type post \
  --limit 50

Origins distinguish warmup, strategy, opportunity, agentic, manual_test, and unresolved legacy unknown work. Execution mode remains a separate field.

Inspect the immutable lifecycle, visibility history, observations, and derived performance for one receipt:

rankhog --json reddit actions inspect ract_...

Both commands require configured organization, website, and managed Reddit account identifiers plus rankhog:read and reddit:activity:read.

Drafts

Drafts are still available for manual workflows. Create a draft from stdin:

draft.json:

{
  "subreddit": "SaaS",
  "title": "A useful Reddit-safe title",
  "body": "A helpful draft body."
}

cat draft.json | rankhog --json drafts create \
  --input - \
  --idempotency-key "draft-2026-06-17-001"

Agent Behavior

The CLI avoids prompts and spinners in JSON mode. Errors are machine-readable and use stable exit codes:

• 0: success.
• 1: command or API failure.
• 3: authentication is required.

CLI execution respects the selected identity's Reddit account protection policy. Weighted rolling budgets and minimum spacing can delay or block an action. The CLI cannot raise or remove those human-owned limits.

Next: read the API reference for HTTP automation or MCP for OAuth tool calls.