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.
Step 1: Create your Virlo account for free
Step 2: Install virlo-cli
Install the binary globally, or skip installing and call it with
npx virlo-clifollowed by the command. The binary is namedvirlo.Terminalnpm install -g virlo-cliStep 3: Save your key
virlo setupasks for yourvirlo_tkn_key, validates it and writes it to~/.virlo/config.json. On CI or a shared box, setVIRLO_API_KEYinstead so nothing touches disk.virlo whoamishows which source is active.Terminalvirlo setup virlo whoamiStep 4: Install the agent skill
This writes a SKILL.md covering every command group, the async model and how to read results.
--globaltargets~/.claude/skills/virlo/SKILL.md;--dirpoints it at any skills folder your agent reads, andvirlo skill printdumps it for agents with their own format.Terminalvirlo skill install --global # or: virlo skill install --dir ./.agents/skills/virloStep 5: Hand the agent a task
Ask in plain English. The skill tells the agent to add
--jsonand to pass-ywhen it confirms runs non-interactively.Your first promptUse 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?
| Option | Install | How the agent uses it | Pick it when |
|---|---|---|---|
| Virlo CLI | npm install -g virlo-cli | Runs virlo commands in a shell and parses --json | Your agent has a terminal, or you want cron jobs and CI scripts |
| Virlo MCP server | https://dev.virlo.ai/api/mcp/mcp in the agent's MCP config | Calls typed tools with OAuth or a bearer key | The agent supports MCP and has no shell, such as a chat app |
| Agent skills | npx skills add Virlo-AI/Virlo-Agent-Plugin | Loads instructions for ranking and planning on top of the server | You want better tool choices from Claude Code, Codex, Cursor or Gemini CLI |
| CLI skill file | virlo skill install | Teaches the agent the CLI surface and safe defaults | Your agent runs the CLI and you want fewer wrong flags |
Which virlo commands do agents use most?
| Command | What comes back |
|---|---|
virlo trends digest | Today's trends across TikTok and Instagram |
virlo hashtags list | Hashtags ranked by recent use |
virlo sounds trending | Sounds rising on TikTok and Instagram Reels |
virlo satellite creator tiktok @[handle] --include videos,outliers | A creator's profile, recent videos and the ones that beat their usual views |
virlo satellite video-outlier [url] --platform tiktok | Why 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
| Question your app asks | Tool it calls | Top answer |
|---|---|---|
| Which format are most creators copying? | get_content_trends | My 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_hooks | POV setup: 32.9% reach a Virality Score of 18+ |
| Which hook type wins most often on Instagram? | search_hooks | Comparison: 19.0% reach a Virality Score of 18+ |
| What is the second trend to copy? | get_content_trends | While 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 freeHow 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:
| Code | Meaning | Typical agent reaction |
|---|---|---|
0 | OK | Parse stdout and continue |
2 | Usage or validation error | Fix the flags; often a missing -y or bad platform value |
3 | Auth or config problem | Run virlo whoami, then virlo setup or set VIRLO_API_KEY |
5 | Rate limited | Back off and retry |
6 | Not found | Check the id, handle or URL |
7 | Network | Retry; 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 setupstores the key in plain text at~/.virlo/config.jsonwith owner-only permissions; preferVIRLO_API_KEYon 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 digestrefresh 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.
More AI assistant guides
- AI assistant guides
- Claude
- Claude Code
- Cursor
- MCP server
- TikTok MCP server
- Instagram MCP server
- ChatGPT
- ChatGPT dots
- OpenAI Codex
- Gemini CLI
- Grok Build
- Claude Cowork
- n8n
- Zapier
- Grok Bot
- Muse
- Claude Duet
- Hermes Agent
- Kimi K3
- Cue
- Manus
- Perplexity Computer
- Paperclip
- OpenClaw
- NanoClaw
- DeepSeek
- ChatGPT agent
- Perplexity
- Microsoft Copilot
- Le Chat
- Notion
- Slack
- Discord
- Telegram
- Google Sheets
- Windsurf
- VS Code
- GitHub Copilot
- Cline
- JetBrains
- Kiro
- Google Antigravity
- goose
- Warp
- OpenCode
- Zed
- Amp
- Factory Droid
- Raycast
- Lovable
- Replit
- Bolt.new
- v0
- Ollama
- LM Studio
- Open WebUI
- LibreChat
- Make
- Pipedream
- Gumloop
- Lindy
- Relevance AI
- Airtable
- ClickUp
- Dify
- Flowise
- LangChain
- CrewAI
- OpenAI Agents SDK
- Mastra
- Vercel AI SDK
- Claude Agent SDK