Guide

Overview

With SOLARI CLI and MCP, you can use Instagram, TikTok, and Threads data that SOLARI has collected — from a terminal, a script, or an agent. catalog looks up accounts and posts SOLARI already has. insight returns rankings, similar accounts, ads, and trends SOLARI computed. fetch adds one exact handle to the catalog as an account or as posts.

$ solari insight instagram account similar username=oliveyoung_official limit=10
$ solari insight instagram brand lookalike content username=innisfreeofficial limit=10
$ solari insight instagram content trend clusters region=KR since_days=7

Install

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

$ solari --version
1.0.0-alpha.9

Quickstart

$ solari auth login          # opens a browser; sign in with your SOLARI account
$ solari                     # catalog, insight, and fetch
$ solari catalog instagram account   # a group path lists its tools
$ solari catalog instagram account search --help    # parameters, without calling

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

Find an account_id, then pass it on:

$ solari catalog 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 insight instagram brand ad stats username=innisfreeofficial
$ solari insight instagram brand top collaborators username=innisfreeofficial limit=20

query_type=bio searches what accounts write about themselves:

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

The command model

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

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

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

solari help all

Every command, tool, and parameter on one page. Add --json for a machine-readable version.

solari get <path ...>

Runs a tool. A half-finished path fails instead of listing.

solari cache refresh

Refresh the tool list on your machine now.

Authentication

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

Server, account, and when the sign-in runs out. Exit code 3 means 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.

Output and piping

Results go to stdout. Prompts go to stderr, so a pipe only carries data.

--json

Raw JSON. The payload is the JSON string at content[0].text.

--ndjson

One JSON object per line. Envelope fields like total go to stderr.

--refresh

Fetch the tool list from the server, skipping the local copy.

--verbose, -v

Log progress to stderr. Secrets are hidden.

$ solari insight 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. An environment variable overrides for that one command.

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

server · SOLARI_SERVER

SOLARI server. Default https://solari.sh.

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.

SOLARI_TOKEN

A bearer access token (from solari auth token) that stands in for the stored sign-in on every command. See From your own code.

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.

Agents

set up solari.sh/get-started.md

solari init registers the CLI with agents on this machine. solari init --remove undoes it.

solari init            # checkbox of every CLI (all on; space toggles, enter installs)
solari init claude     # just one target
solari init --yes      # skip the picker, install all
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

Add .md to any page URL. The whole reference is also one file.

/get-started.md

Agent setup page.

/llms.txt

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

/llms-full.txt

The entire documentation — guide and every tool — concatenated into one Markdown file.

/docs/tools.md

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

From your own code

The same read-only tools the CLI runs are served as a REST API at https://solari.sh/mcp/api/v1, with official TypeScript and Python SDKs on top, and as an MCP server for agents. One access token works for all of them.

Get a token

$ solari auth token
$ solari auth token --json

Prints the access token of the signed-in account, refreshing it first when it has run out. --json adds expires_at, the endpoint, and the account. A token is good for eight hours; treat it as a secret, because it reads your SOLARI account until then.

Run the CLI without a browser

$ export SOLARI_TOKEN=<token from a signed-in machine>
$ solari catalog instagram account search query=nike --json

With SOLARI_TOKEN set, every command runs with no sign-in on that machine — CI jobs, containers, servers with no browser. The CLI never touches ~/.solari/credentials.json then, and the tool cache is keyed by the token, so app tools from another account never leak in. For jobs that outlive a token, keep a signed-in ~/.solari (or point SOLARI_HOME at one) instead: the CLI refreshes it on its own.

Call the REST API

$ curl -sS https://solari.sh/mcp/api/v1/tools/solari_catalog_instagram_account_search \
  -H "Authorization: Bearer $(solari auth token)" \
  -H "Content-Type: application/json" \
  -d '{"query":"nike","limit":3}'

POST the tool's arguments as a JSON object to /tools/<name>; the response is the tool's JSON payload. GET /tools lists every tool with its input schema, and errors come back as { error: { code, message } }. The full reference, including every error code, is on the API page.

Use an SDK

import { Solari } from "@brandazine/solari-sdk";

const solari = new Solari({ token: process.env.SOLARI_TOKEN });
const hits = await solari.tools.catalog.instagram.account.search({ query: "nike", limit: 3 });

from solari_sdk import Solari

solari = Solari()  # reads SOLARI_TOKEN
hits = solari.tools.catalog.instagram.account.search(query="nike", limit=3)

npm install @brandazine/solari-sdk, or pip install solari-sdk. Both are thin wrappers over the REST API with no dependencies; dotted paths join into tool names under the solari_ prefix.

Or MCP from code

Any MCP client can also call https://solari.sh/mcp directly with the same bearer token. The endpoint is stateless, so a single tools/call request works without an initialize handshake.

Errors and exit codes

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. Sign in again.

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

• content search and content aggregate: KR, JP, US, TW, about the last 6 months.
• Account, brand, and post tools: full history, no region cap.
• KR has the deepest coverage of every region.
• Counts are exact up to 10,000. TikTok search stops paging at 9,800.

Identifiers

• account_id is per platform. Instagram and TikTok ids are not interchangeable.
• Pass account_id or username. account_id wins if both are set.
• post_id is per platform. Public ids are slug (Instagram) or video_id (TikTok).

FAQ

I want to change SOLARI data.

No. Every tool is read-only.

I want to use this with Claude.

Yes. Run solari init to introduce the CLI to the agents on your machine, or connect to the MCP server directly.

Search says there are no results.

Account search matches the username or display name as written. For content search, use KR, JP, US, or TW, and dates inside the last six months.

I want to know if there's a fee.

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