CLI

The viraloop CLI wraps the whole API in commands that work for humans and for scripts and agents.

Install

bash

npm install -g viraloop
viraloop --version

The command is viraloop (alias vl). Without installing, use npx -y viraloop <command>.

Authenticate

Two options:

viraloop login: paste an API key from https://viraloop.io/settings/developers and it is stored for future commands
VIRALOOP_API_KEY environment variable: nothing to store; ideal for CI and agents

Verify with viraloop whoami.

Commands

viraloop whoami: introspect the API key (GET /me)
viraloop credits: credit balance and ledger (GET /credits)
viraloop workspaces list: list workspaces (GET /workspaces)
viraloop workspaces get <id>: get a workspace (GET /workspaces/{id})
viraloop workspaces create <name> [--website <url>]: create a workspace; the brand profile builds in the background (POST /workspaces)
viraloop accounts list: list connected social accounts (GET /accounts)
viraloop generate: generate AI post suggestions (POST /generations)
viraloop generations list: list suggestions (GET /generations)
viraloop generations get <id>: get a suggestion (GET /generations/{id})
viraloop generations accept <id>: accept a suggestion into the library, returns contentId (POST /generations/{id}/accept)
viraloop posts create: create and schedule a post (POST /posts)
viraloop posts list: list posts (GET /posts)
viraloop posts get <id>: get a post with per-platform results (GET /posts/{id})
viraloop posts cancel <id>: cancel a scheduled post (DELETE /posts/{id})
viraloop calendar: posting calendar (GET /calendar)
viraloop content download <id>: fetch a content piece's finished media files (GET /content/{id}/download)

Commands default to the team's default workspace; pass --workspace <id> to target another.

Scripting and agents: --json

Always pass --json when running from a script or agent, and parse the success field. The output is the raw API envelope, so the API reference documents every field.

bash

viraloop generate --count 3 --json
viraloop posts create --suggestion <id> --accounts tiktok:<accountId>,youtube:<accountId2> \
  --when asap --wait --json

--accounts takes comma-separated platform:id pairs (ids from viraloop accounts list). Use --when asap or --at "2026-07-04T15:00:00Z" (with optional --timezone as an IANA name) for timing, --video-url or repeatable --image-url plus --caption for your own media.

Exit codes

0: success
2: authentication failed (unauthorized); re-run viraloop login or fix VIRALOOP_API_KEY
3: insufficient_credits; top up at https://viraloop.io/settings/billing
4: rate_limited; wait and retry (respect Retry-After)
1: any other error

--wait

viraloop posts create --wait polls the created post until a terminal state (posted, partial, completed, failed; a renderStatus of failed is also terminal) and prints the final post including per-platform postUrls. Without --wait, poll viraloop posts get <postId> --json yourself. Do not use --wait for far-future scheduled posts: it waits until the post actually publishes.