Guide

Overview

SOLARI CLI puts SOLARI's creator and content data in your terminal. Look up any brand or creator on Instagram or TikTok, measure their sponsored-content footprint, search what people actually say in captions and video transcripts, and read what is trending right now — as plain commands that compose with jq, shell scripts, and AI coding agents.

SOLARI is also available as an MCP server, so apps like Claude Desktop and ChatGPT can reach it without the CLI. Either way you get the same 26 tools and the same read-only access.

$ solari instagram account search query=oliveyoung brands_only=true
$ solari tiktok content search query=sunscreen region=KR
$ solari instagram content trending region=KR limit=10 --json

Install

The CLI is one file, with nothing else to install alongside it. Pick whichever method matches how you usually install tools — they all give you the same thing.

curl -fsSL https://solari.sh/install | sh

Then confirm the install:

$ solari --version
1.0.0-alpha.9

Quickstart

Sign in once, then look through the tools and run one. Looking around is answered from a copy kept on your own machine, so it comes back instantly.

$ solari auth login          # opens a browser; sign in with your SOLARI account
$ solari                     # platforms and groups available to you
$ solari instagram account   # a group path lists its tools
$ solari instagram account search --help    # parameters, without calling

$ solari instagram account search query=oliveyoung brands_only=true limit=3

Most work starts by turning a name into an account_id, then passing that id to the other tools:

$ solari instagram account search query=innisfree brands_only=true --json \
    | jq -r '.content[0].text | fromjson | .items[0].account_id'
018cabce-14cc-7544-8890-7811ec33ef74

$ solari instagram brand ad stats username=innisfreeofficial
$ solari instagram brand top collaborators username=innisfreeofficial limit=20

A name is not the only way in. query_type=bio searches what accounts write about themselves, so you can start from a category rather than from a brand you already know:

$ solari instagram account search query="협찬 문의" query_type=bio region=KR limit=10
$ solari instagram account search query=skincare query_type=bio brands_only=true limit=20

The command model

The path is the command. Stop partway and you get a list of what sits under it; type a full tool path and it runs; leave out something the tool needs and it shows you what it takes instead of running. Spaces and underscores work the same, and you can drop the solari_ prefix.

$ solari instagram brand              # lists the group
$ solari brand overview --help        # unambiguous trailing paths resolve while browsing
$ solari instagram brand overview username=innisfreeofficial   # calls

Arguments are key=value pairs. Arrays accept JSON or a comma-separated list.

solari instagram content batch post_ids='["019f505f-…","019f5060-…"]'
solari instagram content batch post_ids=019f505f-…,019f5060-…

solari help all

Every command, tool, and parameter on one page. Answered from your own machine; add --json for a machine-readable version. Handy for handing an AI agent everything at once.

solari get <path ...>

Runs a tool and nothing else — it refuses a half-finished path. Use it in scripts, where a typo should fail rather than quietly print a list.

solari cache refresh

Update the tool list on your machine right away, instead of waiting for it to refresh on its own.

Authentication

Signing in opens your browser, the same way signing in to any website does.

solari auth login

Opens your browser. Where it cannot — over SSH, or when an agent is running the command — it prints the sign-in link instead.

solari auth list

List the SOLARI accounts you are signed in to.

solari auth switch <account>

Switch to another account you are already signed in to, without opening a browser.

solari auth status

Show which server and account you are on, what you can reach, and when the sign-in runs out. Exit code 3 means someone has to sign in again.

solari auth logout

Sign out. Add --all to sign out of every account at once.

If the browser cannot hand you back to the machine you ran the command on — over SSH, or inside a container — finish signing in, then copy the address out of the browser's address bar and paste it into the prompt that is waiting for it.

What you can reach

Access is read-only and it covers every tool. Once you have signed in you can call all 26 — there are no tiers and nothing to unlock one tool at a time. Instead of plan limits, there is a cap on how often a single account can call.

Output and piping

Results go to standard output; prompts and hints go to standard error, so a pipe only ever carries data. Colour is added only when you are looking at a terminal — never into a pipe, and never into JSON.

--json

Raw JSON. A tool's answer arrives wrapped one layer deep — the data itself is the JSON string at content[0].text.

--ndjson

One JSON object per line: the items of a response, one at a time. What surrounds them (total, has_more, and so on) goes to standard error. Made for jq and for writing large pulls straight into a file.

--refresh

Skip the copy on your machine and get the tool list fresh from the server.

--color[=always|never|auto]

Colour the help and the tool listings. auto (the default) adds colour only when you are looking at a terminal; NO_COLOR=1 turns it off, FORCE_COLOR=1 turns it on even in a pipe. --no-color is the same as never.

--verbose, -v

Print a running log to standard error while the command works. Secrets are hidden.

$ solari instagram brand ad posts username=innisfreeofficial months=24 limit=200 --ndjson >> ads.ndjson
$ jq -s 'group_by(.username) | map({creator: .[0].username, posts: length})' ads.ndjson

Configuration

Settings live in ~/.solari/config.json. Every setting also has an environment variable, which takes over for that one command. solari config list shows the value in effect and where it came from.

$ solari config list
$ solari config set server https://solari.sh
$ solari config unset server

server · SOLARI_SERVER

Which SOLARI server to talk to. Defaults to https://solari.sh, and a successful sign-in remembers the server it used.

cacheTtl · SOLARI_CACHE_TTL

How long, in seconds, the tool list on your machine counts as current. Default 900; 0 always asks the server.

cacheShadow · SOLARI_CACHE_SHADOW

After answering from your machine, quietly update the tool list in the background. Default true.

callTimeout · SOLARI_CALL_TIMEOUT

Seconds to wait for a tool call. Default 150.

catalogTimeout · SOLARI_CATALOG_TIMEOUT

Seconds to wait for the tool list. Default 8, so an unreachable server fails quickly instead of hanging.

SOLARI_HOME

Keep SOLARI's files somewhere other than ~/.solari.

SOLARI_NO_UPDATE_CHECK=1

Turn the daily update check off entirely. NO_UPDATE_NOTIFIER=1 does the same.

The tool list is answered from your machine first, so browsing and checking parameters are instant; once the copy is older than the timeout above, it is refreshed in the background. A path the copy does not know is looked up on the spot, so a tool added on the server works right away.

Agents

If you already work with an agent that runs commands, hand it this one line and stop reading. It fetches a short setup page written for agents rather than people, then does the rest itself — connects or installs, walks you through sign-in, and registers SOLARI with the tools on your machine.

set up solari.sh/get-started.md

The rest of this section is what that page does, in case you would rather do it by hand.

solari init tells the AI agents on your machine that the CLI exists, so they reach for it on their own when a question is about Instagram or TikTok data. It sets up a skill for Claude Code, a section it manages in Codex's AGENTS.md, and tab completion in zsh. solari init --remove undoes all of it.

solari init            # claude + codex + zsh, with a confirmation for each
solari init claude     # just one target
solari init --remove

Use the CLI in a terminal, in scripts, and with agents that run commands. Use MCP for apps that connect to servers themselves, like Claude Desktop and ChatGPT.

Machine-readable docs

Every page on this site has a Markdown twin at the same address with .md on the end, and the whole reference is available as one file to hand to a model.

/get-started.md

The setup page the line at the top of this section points to. Written for an agent to act on.

/llms.txt

An index of the documentation, in the llms.txt format.

/llms-full.txt

The entire documentation — guide and all 26 tools — concatenated into one Markdown file.

/docs/tools.md

Any page, as Markdown. Add ?lang=ko or ?lang=ja for the other languages.

Connect over MCP

SOLARI also runs as a remote MCP server. A host with MCP support connects to it directly and gets the same read-only tools as the CLI, with nothing to install. One address is all it needs:

https://solari.sh/mcp

The first connection opens a browser to sign in with your SOLARI account. The host then asks which tools it may call, and nothing runs until you approve. Access is read-only from every host.

Claude Desktop

Open Settings and choose Customize at the bottom of the sidebar.

Go to Connectors, press Add, and fill in the dialog: a name for the connectors list, and the address above.

Continue walks you through sign-in once. After that SOLARI sits in your connectors list and its tools are available in any chat. claude.ai works the same way.

Claude Code

One command registers the server.

claude mcp add --transport http solari https://solari.sh/mcp

Claude Code asks you to sign in the first time it reaches the server. /mcp shows the connection and lets you start that yourself.

ChatGPT

ChatGPT connects the same way as Claude Desktop: add the address as a custom connector under Settings → Connectors, then sign in. Custom connectors are a paid-plan feature in ChatGPT.

Other hosts

Other apps that support remote MCP servers can connect too. Most of them take an entry like this in their settings file:

{
  "mcpServers": {
    "solari": {
      "url": "https://solari.sh/mcp"
    }
  }
}

Errors and exit codes

Every error says what to do next, and the exit codes are stable enough to branch on in a script.

0

Success.

1

The tool or the server failed.

2

You typed something the CLI could not use — an unknown path, a missing argument, or a bad value.

3

You need to sign in. Only a person can finish the browser sign-in, so an agent should say so rather than keep trying.

Common tool errors

auth expired, reconnect the connector

Your sign-in ran out. Run solari auth login again, or reconnect the connector in your app.

SOLARI access denied (403)

SOLARI refused the call. Every tool is open to any signed-in account, so this points at the account itself — sign in again, and tell us if it keeps happening.

rate limited, retry shortly

Too many calls in a short window. Wait a moment and try again.

SOLARI upstream timed out

The call took too long — 90 seconds for most tools, 120 for the aggregate and trend-cluster ones. Narrow the range or lower the limit and try again.

Data coverage

What SOLARI can answer depends on which tool you use. Two limits matter most: which regions are covered, and how far back the data goes.

• Keyword search and grouped counts (content search and content aggregate, on both platforms) cover KR, JP, US, and TW, and hold roughly the last 6 months. Ask for an earlier date and it is moved up to the oldest one available; the response tells you which date was actually used.
• Looking up an account, a brand, or a post uses the full history, and is not limited to those four regions or to six months.
• KR has the deepest coverage of every region.
• Result counts are exact up to 10,000 and stop climbing there. TikTok search stops paging at 9,800 — to go further, narrow the date range.

Identifiers

• account_id is a SOLARI account UUID, issued per platform. An Instagram account_id and a TikTok account_id are different values and never interchangeable, even for the same brand.
• Every account slot accepts either an account_id UUID or a username, and account_id wins when both are set.
• post_id is a SOLARI post UUID, also per platform. Its public counterpart is slug (the Instagram shortcode) or video_id (the numeric TikTok id).

FAQ

Can the CLI modify my SOLARI data?

No. Every tool is read-only — there is nothing in the CLI or the MCP server that can write.

Can I use it with agents like Claude?

Yes. Run solari init to introduce the CLI to the agents on your machine, or connect to the MCP server directly. Both are read-only.

Why did my search return nothing?

Account search reads handles from the start of the name, and display names anywhere in them. What you type has to actually appear in one of the two, so a nickname or an abbreviation will not find it — try the spelling the account uses itself. For content search, check that the region is KR, JP, US, or TW and that the dates fall inside the last six months.

Is there a fee?

SOLARI CLI is free to use for now. We will announce pricing before anything changes.