Command line

Sign in, upload, publish, schedule and diagnose from a script or terminal.

Install

npm install -g castrook@0.5.0

Requires Node.js 20.3 or later.

Sign in

castrook login
castrook whoami
castrook accounts list --json
castrook usage --json

Login uses the same OAuth consent as MCP and starts in Test mode. Check the callback, workspace and permissions in the browser. Credentials stay in a local file with restricted permissions. For server automation, use CASTROOK_API_KEY in the environment.

Use --mode live to request Live, --scopes for a space-separated permission list, or --no-browser if the CLI cannot open a browser. A flag cannot override the mode bound to an existing grant.

Create a Test post

Request the scopes required for creating a simulated account and post, then explicitly select the write permissions in the browser:

castrook login --scopes "accounts:read accounts:write posts:read posts:write usage:read"
castrook accounts create-test --data @account.json --json

{"platform":"facebook","name":"API demo"}

Save the returned account ID in post.json:

{
  "text": "Hello from Castrook.",
  "account_ids": ["acc_replace_with_your_test_account_id"],
  "platform_options": {
    "facebook": { "sandbox_outcome": "published" }
  }
}

castrook posts create --data @post.json --idempotency-key cli-first-post-v1 --json
castrook posts get pst_replace_with_returned_id --json
castrook posts wait pst_replace_with_returned_id --json

Keep the same body and key for the exact retry. --data - accepts stdin; --json returns pipeable JSON on stdout, while errors and progress use stderr.

Work with every resource

castrook profiles list --all --json
castrook accounts boards acc_pinterest --all --json
castrook accounts board-sections acc_pinterest 123456789 --all --json
castrook media upload ./launch.mp4 --profile prf_your_profile_id --json
castrook analytics summary --json
castrook comments list --account acc_your_account_id --post pst_your_post_id --json
castrook logs list --json

Resource commands cover profiles, customer connections, accounts, media, posts, analytics, comments, webhooks, deliveries, request logs and usage. List commands accept --all for pagination. Run a command with --help for arguments and filters.

login --publish requests post and media write scopes. Creating a new Test account additionally needs accounts:write. For webhooks, create --data @hook.json --secret-file PATH writes the one-time signing secret to a protected file.

Upload and recover

Uploads hash the file, request a private ticket, transfer directly and verify immutable bytes. Videos are at most 128 MiB; still images at most 20 MiB and 24 megapixels. Save the asset ID if a transfer is interrupted, then inspect or complete that asset before uploading another copy.

End access

castrook logout

Logout revokes the OAuth grant. --local-only removes only local credentials. Never put a credential in command arguments, logs or checked-in configuration.

Read this guide as Markdown or use the machine manifest.