Viraloop CLI

Command line client for the Viraloop public API: generate AI short-form social videos and schedule them to TikTok, Instagram and YouTube. Also ships a local MCP server so agents can use Viraloop as tools.

Full API reference and guides: https://viraloop.io/developers

Install

npm install -g viraloop

Requires Node 18 or newer. The package installs two equivalent commands: viraloop and vl.

Authentication

Create an API key in the dashboard at https://viraloop.io/settings/developers, then either log in once:

viraloop login

This verifies the key against GET /me and saves it to ~/.viraloop/config.json (file mode 600). Or use an environment variable instead:

export VIRALOOP_API_KEY=vl_live_...
viraloop whoami

Key precedence: --api-key flag, then VIRALOOP_API_KEY, then the config file. The base URL can be overridden with --api-url or VIRALOOP_API_URL. Use viraloop logout to remove the saved key.

Commands

| Command | Description | | ---------------------------------- | --------------------------------------------------------------------- | | viraloop login | Save an API key to ~/.viraloop/config.json (verified against /me) | | viraloop logout | Remove the saved API key | | viraloop whoami | Introspect the API key | | viraloop credits | Credit balance and ledger | | viraloop workspaces list | List workspaces | | viraloop workspaces get <id> | Get a workspace | | viraloop accounts list | List connected social accounts | | viraloop generate | Generate AI post suggestions | | viraloop generations list | List suggestions | | viraloop generations get <id> | Get a suggestion | | viraloop posts create | Create and schedule a post | | viraloop posts list | List posts | | viraloop posts get <id> | Get a post with per-platform results | | viraloop posts cancel <id> | Cancel a scheduled post | | viraloop calendar | Posting calendar | | viraloop campaigns create | Create a draft campaign (name, cadence, accounts, settings) | | viraloop campaigns list | List campaigns and the monthly quota | | viraloop campaigns get <id> | Get a campaign (--wait polls while generating) | | viraloop campaigns update <id> | Update a draft campaign | | viraloop campaigns generate <id> | Generate the campaign's posts (--wait polls to review) | | viraloop campaigns launch <id> | Launch a reviewed campaign | | viraloop campaigns cancel <id> | Cancel a campaign | | viraloop campaigns posts <id> | List a campaign's generated posts | | viraloop influencers list | List AI influencers | | viraloop influencers create | Create an AI influencer from a base photo | | viraloop influencers get <id> | Get an influencer | | viraloop videos create | Generate a talking-head video (20 credits) | | viraloop videos list | List an influencer's videos | | viraloop videos get <id> | Get a video's status | | viraloop assets list | List media assets | | viraloop mcp | Start the local MCP server over stdio |

Global options: --json, --api-key <key>, --api-url <url>, --workspace <id> (passed as workspaceId on endpoints that accept it). Run any command with --help for its flags.

Examples

# Generate 3 suggestions, review them, then publish one
viraloop generate --count 3 --format walloftext
viraloop generations list --status pending

# Find your connected account ids
viraloop accounts list

# Publish a suggestion to TikTok as soon as the render is ready
viraloop posts create \
  --suggestion 665f1b2a9c31a2b3c4d5e701 \
  --accounts tiktok:665f1b2a9c31a2b3c4d5e700 \
  --when asap --wait

# Schedule your own video for later
viraloop posts create \
  --video-url https://example.com/video.mp4 \
  --caption "Launch day" --hashtags launch,startup \
  --accounts tiktok:665f...,youtube:665f... \
  --at 2026-07-03T10:00:00Z --timezone America/New_York

# What is already queued this week?
viraloop calendar --from 2026-07-01 --to 2026-07-07

# Run a one-week campaign: create, generate, review, launch
viraloop campaigns create --name "July launch week" \
  --posts-per-day 2 --length-days 7 --timezone America/New_York \
  --time-slots 09:00,15:00 --accounts tiktok:665f1b2a9c31a2b3c4d5e700
viraloop campaigns generate 665f1b2a9c31a2b3c4d5e710 --wait

# Generation settings are flags too (create and update):
#   --content-mix walloftext:50,slideshow:50   format weights
#   --remix-ratio 30                           share remixed from trending
#   --angle "Client Revision Hell:60"          repeatable angle weights
#   --mention-business often                   never|rarely|sometimes|often|always
#   --gender-preference women --own-media-mix 20 --influencer-frequency 50
viraloop campaigns posts 665f1b2a9c31a2b3c4d5e710
viraloop campaigns launch 665f1b2a9c31a2b3c4d5e710

# Generate a talking-head video of an AI influencer (20 credits)
viraloop influencers list
viraloop videos create --influencer 665f1b2a9c31a2b3c4d5e720 \
  --script "Three things I wish I knew before my first marathon" \
  --duration 10 --wait

JSON output and exit codes

Pass --json to print the raw API envelope ({ "success": true, "data": ... }). When stdout is not a TTY (pipes, scripts, CI), JSON is printed automatically, so viraloop posts list | jq just works.

Errors are written to stderr as error (<type>): <message> with these exit codes:

| Exit code | Meaning | | --------- | ---------------------------------------------------------------------- | | 0 | Success | | 1 | Any other error (invalid input, not found, conflict, network, timeout) | | 2 | unauthorized or forbidden_scope | | 3 | insufficient_credits | | 4 | rate_limited |

On HTTP 429 the client retries once after the Retry-After interval (capped at 30 seconds).

Waiting for async work

posts create and posts get accept --wait (with --timeout <sec>, default 600). The CLI polls the post every 5 seconds until it reaches a terminal status (posted, partial, completed, failed) or the render fails, then prints the final post with per-platform results.

The same flags work for campaign generation and video rendering: campaigns generate <id> --wait and campaigns get <id> --wait poll until the campaign leaves generating (normally landing in review), while videos create --wait and videos get <id> --wait poll until the video is completed or failed.

MCP server

The CLI doubles as a local MCP server over stdio, exposing the Viraloop API as tools (viraloop_get_me, viraloop_generate_content, viraloop_create_post, and more). Add it to Claude Code:

claude mcp add viraloop -- npx -y viraloop mcp

Make sure VIRALOOP_API_KEY is set in the environment (or run viraloop login first).

Prefer a hosted option? Viraloop also serves a remote MCP endpoint at https://viraloop.io/api/v1/mcp (Authorization: Bearer vl_live_...), no local install needed.

Links

• Developer docs: https://viraloop.io/developers
• API keys: https://viraloop.io/settings/developers
• Agent skill: https://github.com/Viraloop/viraloop-skill