machopost

CLI for the machopost publishing API — a thin 1:1 wrapper over the public REST API (ADR-0006). Every command prints JSON on stdout; errors are structured JSON with a non-zero exit code, so agent loops can parse output unconditionally and branch on the exit code.

Configuration

export MACHOPOST_API_KEY=mp_...

MACHOPOST_API_KEY (or --api-key) is the canonical agent credential and the only required configuration. The CLI talks to the production API (https://machopost.machobear.com) by default; set MACHOPOST_API_URL (or pass --api-url, which takes precedence) only to point at a local dev server or a custom deployment.

machopost is also an OAuth 2.1 authorization server, and an OAuth access token works everywhere an API key does — pass it through the same variable or flag; the API resolves both from the same Authorization: Bearer header. The differences: an OAuth token is confined to the workspace and scopes the human granted its app on machopost's consent page, and it expires after about an hour (the app holds the refresh token, not the CLI). Obtaining one is a human-in-the-loop flow — the app sends its user through /.well-known/oauth-authorization-server discovery, authorization, and the consent page; the CLI plays no part in it. API keys remain the canonical credential for agents.

Human login

machopost login is a convenience for a human operator (ADR-0005: API keys stay the canonical agent credential). It runs OAuth 2.0 device authorization: the CLI prints a verification URL and a short code, the human opens the URL in a browser and approves, and the CLI polls until the session is granted and stores it under ${XDG_CONFIG_HOME:-~/.config}/machopost/credentials.json (mode 0600). machopost logout deletes it.

Credential precedence: an explicit --api-key / MACHOPOST_API_KEY always wins; otherwise a stored device session (matching the active API URL) is used. Both resolve to the same Authorization: Bearer credential the API expects.

Commands

machopost login
machopost logout
machopost health
machopost me
machopost channels:list
machopost channels:connect <provider-id>
machopost providers:list
machopost providers:constraints <provider-id>
machopost media:upload <file-or-url> [--idempotency-key KEY]
machopost media:get <media-id>
machopost posts:create --content TEXT --media ID... (--channel ID... | --targets JSON) \
  --schedule now|draft|ISO [--timezone TZ] [--idempotency-key KEY]
machopost posts:update <post-id> --schedule now|ISO [--timezone TZ]
machopost posts:list [--from ISO] [--to ISO]
machopost posts:get <post-id>
machopost posts:delete <post-id>
machopost deliveries:retry <delivery-id>
machopost webhooks:list
machopost webhooks:create <url> [--event TYPE...]
machopost webhooks:delete <webhook-id>

media:upload sends a multipart upload for a local path and server-side URL ingestion for an http(s):// source. posts:create --targets takes a JSON array of {channelId, variant?} for per-channel captions or story posts; --channel (repeatable) is the shorthand when no variants are needed. --content is always required — pass --content "" explicitly for a caption-less post. posts:update publishes a draft (--schedule now) or reschedules a post whose deliveries have not started.

Connecting a channel requires a human to complete provider OAuth in a browser. channels:connect only fetches the OAuth URL — callers surface it to a human and never follow it themselves.

Requires Node >= 24. In the monorepo the bin runs the TypeScript source directly; the published package ships compiled dist/ (pnpm build).