The AI agents CLI for TikTok and Instagram research

Updated

Virlo is social listening for TikTok and Instagram Reels. A coding agent can run any command you allow, yet none of them ships with a view of what is trending on TikTok or Instagram. Install virlo-cli and Claude Code, Codex, Gemini CLI, OpenClaw or any shell-capable agent can pull trends, hooks, sounds and outlier videos from a database of 23.1M viral videos as clean JSON. An AI agent CLI is a command-line tool built for agents as well as people: predictable subcommands, machine-readable output and exit codes a script can branch on.

  • `--json` on every command, errors on stderr
  • Exit codes built for branching
  • `virlo skill install` teaches your agent the commands

Part of Virlo's AI assistant guides. Prefer tools over shell commands? See the MCP server. Using it from Anthropic's terminal agent? See Claude Code.

How do I install the Virlo CLI for my AI agent?

Node 20 or newer is the only requirement. These steps work the same on macOS, Linux, Windows, a CI runner or a VPS.

  1. Step 1: Create your Virlo account for free

    Create your free Virlo account in under a minute. Already signed up? Open API Keys.
  2. Step 2: Install virlo-cli

    Install the binary globally, or skip installing and call it with npx virlo-cli followed by the command. The binary is named virlo.

    Terminal
    npm install -g virlo-cli
  3. Step 3: Save your key

    virlo setup asks for your virlo_tkn_ key, validates it and writes it to ~/.virlo/config.json. On CI or a shared box, set VIRLO_API_KEY instead so nothing touches disk. virlo whoami shows which source is active.

    Terminal
    virlo setup
    virlo whoami
  4. Step 4: Install the agent skill

    This writes a SKILL.md covering every command group, the async model and how to read results. --global targets ~/.claude/skills/virlo/SKILL.md; --dir points it at any skills folder your agent reads, and virlo skill print dumps it for agents with their own format.

    Terminal
    virlo skill install --global
    # or: virlo skill install --dir ./.agents/skills/virlo
  5. Step 5: Hand the agent a task

    Ask in plain English. The skill tells the agent to add --json and to pass -y when it confirms runs non-interactively.

    Your first prompt
    Use the virlo CLI with --json to get today's trends digest and the TikTok sounds trending this week, then write research/[your niche]-week.md with the 5 ideas worth making and the source video for each.

Settings resolve per call as flag, then environment variable, then config file. That lets one machine run several agents with different keys through --api-key or per-process VIRLO_API_KEY.

CLI vs MCP server vs agent skills: which does my agent need?

OptionInstallHow the agent uses itPick it when
Virlo CLInpm install -g virlo-cliRuns virlo commands in a shell and parses --jsonYour agent has a terminal, or you want cron jobs and CI scripts
Virlo MCP serverhttps://dev.virlo.ai/api/mcp/mcp in the agent's MCP configCalls typed tools with OAuth or a bearer keyThe agent supports MCP and has no shell, such as a chat app
Agent skillsnpx skills add Virlo-AI/Virlo-Agent-PluginLoads instructions for ranking and planning on top of the serverYou want better tool choices from Claude Code, Codex, Cursor or Gemini CLI
CLI skill filevirlo skill installTeaches the agent the CLI surface and safe defaultsYour agent runs the CLI and you want fewer wrong flags

Which virlo commands do agents use most?

CommandWhat comes back
virlo trends digestToday's trends across TikTok and Instagram
virlo hashtags listHashtags ranked by recent use
virlo sounds trendingSounds rising on TikTok and Instagram Reels
virlo satellite creator tiktok @[handle] --include videos,outliersA creator's profile, recent videos and the ones that beat their usual views
virlo satellite video-outlier [url] --platform tiktokWhy one video broke out: hook, format and how far it beat the norm
virlo webhooks create --url … --events …A webhook that pushes events to your endpoint

Add --watch to asynchronous lookups so the command waits for the result. Run virlo [group] --help for every option.

What does the Virlo CLI return right now?

One real answer per question, pulled from Virlo for this page. Your agent gets the full list as JSON from the matching command.

In Virlo's data, 659 creators posted the "My moon my man couple montage" trend in the last 7 days, the top answer the trends tool gives as of November 19, 2026.

As of November 19, 2026 at 13:07 UTC

What does the Virlo CLI return right now?
Question your app asksTool it callsTop answer
Which format are most creators copying?get_content_trendsMy moon my man couple montage: 659 creators this week
Which sound is trending on Instagram Reels?get_trending_sounds"Flower In A Hurricane (feat. Tame Impala, SZA, King Gizzard & the Lizard Wizard) [From GTAVI: Original Score]": 75 Reels in 7 days
Which hook type wins most often on TikTok?search_hooksPOV setup: 32.9% reach a Virality Score of 18+
Which hook type wins most often on Instagram?search_hooksComparison: 19.0% reach a Virality Score of 18+
What is the second trend to copy?get_content_trendsWhile they're out partying btw: 346 creators this week

Every answer, not just the top one

Connect the server and the same tools return the full lists, filters and history.

Start for free

How this sample is made

Source
Virlo's Trends to copy, Instagram sound rankings and daily hook snapshot: the same data the MCP tools read.
Window
Trends: creators in the last 7 days. Sounds: Reels in the last 7 days. Hooks: all hook-tagged videos in the latest snapshot. TikTok and Instagram only.
Method
Each row is the top item for that question, from the data the named tool reads.
As of
Trends November 19, 2026 at 13:07 UTC; sounds November 19, 2026 at 12:03 UTC; hooks November 19, 2026.
Made by
Numbers are pulled automatically from Virlo's data every hour; the text around them is written by the Virlo team.

Suggested citation: Source: Virlo, “The AI agents CLI for TikTok and Instagram research”, virlo.ai/ai-agents-cli

How do agents script the Virlo CLI safely?

With --json, stdout carries only the response data, so it pipes straight into jq or back to the agent. Errors land on stderr as an object with type and message, and paginated lists print one pagination line to stderr. Commands that start a run need -y when called non-interactively or with --json; without it the CLI stops before sending any request.

Exit codes let a wrapper script or agent decide what to do next without reading prose:

Exit codes worth branching on
CodeMeaningTypical agent reaction
0OKParse stdout and continue
2Usage or validation errorFix the flags; often a missing -y or bad platform value
3Auth or config problemRun virlo whoami, then virlo setup or set VIRLO_API_KEY
5Rate limitedBack off and retry
6Not foundCheck the id, handle or URL
7NetworkRetry; VIRLO_TIMEOUT_MS raises the per-request timeout

For push instead of polling, register a webhook: virlo webhooks create --url [your endpoint] --events tracking.outlier_video.detected,content_research_agent.run.completed. Event names such as comet.run.completed are listed in the webhook docs.

What can I ask an agent to do with the Virlo CLI?

Paste into Claude Code, Codex, Gemini CLI, OpenClaw or any agent with shell access. Replace the brackets.

  • Daily file

    Every morning, run virlo trends digest --json -y and append the top 5 entries for [your niche] to research/daily.md with the date.

  • Creator audit

    Run virlo satellite creator tiktok @[handle] --include videos,outliers --json -y --watch and summarise which of their videos broke out and why.

  • Video autopsy

    Use virlo satellite video-outlier [TikTok url] --platform tiktok --json -y --watch and turn the result into a 30-second script for [your product].

  • Sound picker

    Run virlo sounds trending --json and pick the two sounds that fit a [tone] video for [your brand]; save them to content/sounds.md.

  • Hashtag table

    Get virlo hashtags list --json, filter for tags related to [topic], and write a markdown table sorted by use.

  • Webhook receiver

    Build a small endpoint that receives Virlo tracking.outlier_video.detected webhooks and posts the video link and Virality Score to [your Slack webhook].

  • CI check

    Write a CI step that runs virlo whoami --json, fails on exit code 3, and otherwise refreshes data/trends.json.

Virlo CLI vs Virlo MCP server vs agent skills: what is the difference?

Three ways to put Virlo inside an agent. They read the same data and can be combined.

Virlo CLI (this page)

A shell command, virlo, with JSON output and exit codes. Best where an agent has a terminal or a script runs on a schedule.

Virlo MCP server

A hosted endpoint that MCP clients add by URL. Best for chat apps and agents that call tools rather than shell commands.

Claude Code

One agent that can use all three. Its guide covers the plugin and claude mcp add routes.

Warp

A terminal with its own agent. Install the CLI there and the agent can run it like any other command.

What are the limits?

  • The CLI reads public TikTok and Instagram data only. There are no commands that log in to social accounts or publish posts.
  • virlo setup stores the key in plain text at ~/.virlo/config.json with owner-only permissions; prefer VIRLO_API_KEY on shared machines and rotate keys from the dashboard.
  • Asynchronous jobs can report finished before the AI analysis is written; re-read with the matching analysis command if fields come back empty.
  • Trends behind virlo trends digest refresh hourly.
  • Plans and what they include are on pricing.

Frequently asked questions

What is an AI agent CLI?

A command-line tool designed for agents to drive as well as people. Good ones give every command a JSON mode, send errors to stderr in a parseable shape, return distinct exit codes and avoid interactive prompts when a flag says so. virlo-cli follows that pattern for TikTok and Instagram research.

Is there a CLI for TikTok data?

Yes. virlo-cli pulls TikTok and Instagram trends, hashtags, sounds, creator profiles and outlier explanations from the terminal. Install it with npm install -g virlo-cli, run virlo setup with your key, then try virlo trends digest or virlo sounds trending. Add --json to any of them when an agent or script is reading the output.

Should my agent use the CLI or the MCP server?

Use the CLI when the agent has a shell or the job runs from cron or CI, since output pipes cleanly and exit codes drive retries. Use the MCP server when the agent lives in a chat app or only understands tools. Many setups install both.

How do I give the Virlo CLI an API key in CI?

Store the key as a secret and expose it as VIRLO_API_KEY in the job. The CLI checks flags first, then that variable, then the config file, so nothing needs to be written to disk. A quick virlo whoami step confirms the key before the real commands run.

What does virlo skill install do?

It writes a SKILL.md that explains the CLI to an agent: command groups, flags, the async model and how to interpret results. --global puts it in ~/.claude/skills/virlo, --dir writes to any folder you name, and virlo skill print outputs it for agents that store skills elsewhere.

Why does a Virlo command fail without -y?

Commands that start a run ask for confirmation. In a terminal you see a prompt; an agent or any call with --json must pass -y up front. Without it the CLI exits with a validation error before sending anything, which stops an agent from launching runs by accident.

Which agents can run the Virlo CLI?

Any agent allowed to execute shell commands: Claude Code, Codex, Gemini CLI, OpenClaw, Hermes Agent, Goose, Warp and others. Install the binary where the agent runs, set the key, and add the skill file so the agent knows the commands.

Can the Virlo CLI send webhooks?

It registers them. virlo webhooks create takes a URL and a comma-separated list of events, such as tracking.outlier_video.detected or content_research_agent.run.completed, and Virlo then posts those events to your endpoint as they happen. An agent can register one in a single command and react to new outliers without polling.

Put Virlo in your agent’s terminal

Install virlo-cli, add the skill, and let any shell-capable agent research TikTok and Instagram.