# 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](/developers/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 `postUrl`s. 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.