Introduction to OpenQuok CLI

An CLI-first tool for AI agents. Give your agents the OpenQuok CLI to schedule posts, manage integrations, and upload media from the terminal.

3 min read

Connect your agent today

Draft from chat, review in your calendar, and publish only what you approve.

Start for $0

Overview

Warning

For your AI agent to work best with OpenQuok, install the openquok-core:

npx skills add https://github.com/Ratimon/openquok-monorepo/tree/main/agent --skill openquok-core

That updates agent instructions only — it does not install or upgrade the openquok CLI. After adding the skill, run npm install -g @openquok/auto-cli@latest on the same host and check openquok --version.

On OpenClaw (Docker, Telegram), cd to your workspace first (often /data/workspace) — see OpenClaw agent guide.

On ThinkRail, install the skill under ~/.pi/agent/skills/ or the worktree .pi/skills/ — see ThinkRail agent guide.

Or open the skill on GitHub (agent/skills/openquok-core/SKILL.md).

@openquok/auto-cli is the programmatic CLI for the OpenQuok scheduling API — built for automation and AI agents. It wraps the public API so you can schedule posts, manage integrations, and upload media from shell scripts.

CLI documentation

Install and authenticate first, then use command reference, platform recipes, agent host setup, and sibling skills.

CLI Core Usages

Command-by-command recipes for posts, integrations, analytics, and uploads

CLI Examples

End-to-end platform recipes organized by social network

Agent Setup Guides

Run openquok-core with OpenClaw, Hermes, Grok Bot, and ThinkRail

Other skills

Sibling agent skills that extend openquok-core

Installation

Requires Node.js 20.19+ (or 22.12+, or 23+). Older versions may install with warnings or fail at runtime.

npm install -g @openquok/auto-cli

pnpm add -g @openquok/auto-cli

Verify the install:

openquok --help

Authentication

Use OAuth2 device flow, so you never embed client secrets in the CLI, or set a programmatic access token (opo_) for CI and scripts. Full variable reference and self-hosted auth options are on CLI authentication.

Note

Every opo_ token is scoped to a single workspace — the workspace you authorize during device login, or the workspace whose programmatic token you copy from the dashboard. To run the CLI against multiple workspaces, issue or authorize a separate token per workspace.

Option 1: OAuth2 (Suggested)

OAuth2 (device flow) — this will automatically open a browser with a one-time code and approval screen to authorize, then it stores credentials at ~/.openquok/credentials.json as default:

openquok auth:login

Check or clear stored credentials:

# Check current auth status
openquok auth:status

# Remove the stored credentials
openquok auth:logout

Option 2: Programmatic token

Set a workspace programmatic token as an environment variable — see Programmatic token on the authentication page (rotate from Developers → Access in the dashboard).

export OPENQUOK_API_KEY="opo_..."

Tip

Add the env to ~/.bashrc, or ~/.zshrc, etc to Shell profile, so the env variable persists across sessions.

Warning

Stored OAuth2 credentials take priority over OPENQUOK_API_KEY when both are present. Run openquok auth:logout to clear them if you want the env var to be used.

Custom API URL (self-hosted)

If you’re running your own self-hosted openquok backend, point the CLI to your server:

export OPENQUOK_API_URL="https://api.yourserver.com"

CLI device login

openquok auth:login calls the device-flow API at https://cli-auth.openquok.com (override with OPENQUOK_AUTH_SERVER). Your browser opens https://www.openquok.com/cli/device/verify to enter the code — not the cli-auth host. Self-hosted operators: see Configuration - Agent and CLI authentication.

Quick start

Note

All commands output as a JSON, so that it is easier for the CLI to use in scripts and automation pipelines.

List your connected social media channels or accounts:

openquok integrations:list

Create a scheduled post (adjust IDs and timestamps):

openquok posts:create 
  -s "2026-01-01T12:00:00Z" 
  -c "Hello from OpenQuok" 
  -i "<integration-id-1>,<integration-id-2>"

Create an agent draft with a review todo (shown on the account kanban for humans):

openquok posts:create 
  -c "Draft for human review" 
  -s "2026-01-01T12:00:00Z" 
  -t draft 
  -i "<integration-id>" 
  --note "Verify links and hashtags before scheduling"

Upload media (use returned data.id + data.filePath in posts:create; videos over ~4 MB use direct-to-storage automatically):

openquok upload ./image.png
openquok upload ./clip.mp4

List your scheduled posts (defaults to ±30 local calendar days from today when you omit dates):

openquok posts:list

Commands (overview)

Auth

openquok auth:login
openquok auth:status
openquok auth:logout

Integrations

openquok integrations:list
openquok integrations:settings <id>
openquok integrations:trigger <id> <method> [-d '<json>']

Posts

openquok posts:create -c "…" -s "2026-01-01T12:00:00Z" -t draft -i "<integration-id>" --note "Human checklist"
openquok posts:review-todo <post-id> --note "Updated checklist"
openquok posts:list
openquok posts:list --start "2026-01-01T00:00:00Z" --end "2026-02-01T00:00:00Z"
openquok posts:status <post-id> -s draft
openquok posts:delete <post-id>