# SOLARI — Guide

> SOLARI CLI and MCP: creator and brand data in your terminal.

## Overview

SOLARI CLI and MCP bring the Instagram, TikTok, and Threads data SOLARI collects into your terminal, scripts, and AI agents. The tools come in three groups:

- catalog: accounts and posts SOLARI already has.
- insight: results SOLARI computes, such as rankings, similar accounts, ads, and trends.
- fetch: accounts, posts, and Instagram hashtags collected live from the platform.

```console
$ solari insight instagram account similar username=oliveyoung_official limit=10
```

Use the CLI in a terminal or with agents that run commands. Use MCP for apps like Claude Desktop and ChatGPT.

## Install

**macOS**

Shell:
```bash
curl -fsSL https://solari.sh/install | sh
```
Homebrew:
```bash
brew install brandazine/solari/solari
```
npm:
```bash
npm install -g @brandazine/solari
```
uv:
```bash
uv tool install solari-cli
```
uv tool installs the CLI in its own environment and adds it to your PATH, so it does not conflict with a project's dependencies.

**Windows**

PowerShell:
```powershell
irm https://solari.sh/install.ps1 | iex
```
npm:
```bash
npm install -g @brandazine/solari
```
uv:
```bash
uv tool install solari-cli
```
uv tool installs the CLI in its own environment and adds it to your PATH, so it does not conflict with a project's dependencies.

**Linux**

Shell:
```bash
curl -fsSL https://solari.sh/install | sh
```
npm:
```bash
npm install -g @brandazine/solari
```
uv:
```bash
uv tool install solari-cli
```
uv tool installs the CLI in its own environment and adds it to your PATH, so it does not conflict with a project's dependencies.

```console
$ solari --version
1.0.1
```

## Quickstart

```console
$ solari auth login     # sign in through the browser
$ solari                # lists catalog, insight, and fetch
$ solari catalog instagram account search --help   # parameters only
$ solari catalog instagram account search query=innisfree brands_only=true limit=3
```

Pass a username or account_id from the result to the next tool:

```console
$ solari insight instagram brand ad stats username=innisfreeofficial
```

## Command structure

```console
$ solari insight instagram brand       # lists the group
$ solari insight instagram brand overview username=innisfreeofficial
```

Arguments are key=value pairs. Arrays can be JSON or comma-separated, like post_ids=a,b.

- `solari help all` — Every command, tool, and parameter on one page. Tools added in the last 7 days are marked NEW.
- `solari get <path ...>` — Only runs a tool. An incomplete path fails instead of listing the group.
- `solari cache refresh` — Reloads the tool list now and shows what changed.

> New tools arrive without a CLI update. When you see note: SOLARI tools changed, run solari help all.

## Authentication

- `solari auth login` — Signs in through the browser. Over SSH or from an agent, it prints a link instead. --add signs in to another account as well.
- `solari auth list · switch <account>` — Lists signed-in accounts, or switches between them without a browser.
- `solari auth status` — Shows the account and when sign-in expires. Exit code 3 means sign in again.
- `solari auth logout` — Signs out. --all signs out of every account.

If the browser can't get back to the machine running the CLI (SSH, containers), copy the URL from the address bar after signing in and paste it into the prompt.

## Credits and usage

Only successful tool calls use credits. They come from your account's prepaid balance, which the CLI, MCP, and the REST API share, and each page of a paged result counts as a separate call. Failed calls, tool lists, the app catalog, account info, feedback, and balance checks are free.

```console
$ solari usage
```

Shows your plan, credits left and when they expire, and billed calls in the last 30 days. It is free and works at a zero balance. Over MCP, use solari_usage_get.

At zero balance, calls fail with CREDIT_EXHAUSTED (REST: HTTP 402) and are not charged. The error says what to do next.

Plans, trial, and top-ups: https://solari.sh/pricing · Your balance: https://solari.brandazine.com/settings/billing

## Output and piping

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

- `--json` — Raw JSON. The data is the JSON string in content[0].text.
- `--ndjson` — One JSON object per line. Fields like total go to stderr.
- `--verbose, -v` — Logs progress to stderr, with secrets hidden.

Every post row has assets: its media files in order, each with an asset_url you can download. They are stored copies; for the highest quality, use solari instagram download content or solari tiktok download content.

```console
$ solari catalog instagram account posts username=innisfreeofficial limit=200 --ndjson \
    | jq -r '.assets[].asset_url | select(.)' > urls.txt
$ aria2c -i urls.txt -d media -j 8
```

## Feedback from agents

When an agent can't finish a task with SOLARI (missing data or features, too few results, a wrong value, a failing tool), it sends feedback to the SOLARI team on its own and tells you in one line. It leaves out personal data, and SOLARI strips emails, phone numbers, and keys again before saving.

```console
$ solari feedback "brand ad posts returned 3 rows for 24 months" category=insufficient_results
```

## Configuration

Settings are stored in ~/.solari/config.json. An environment variable overrides a setting for that command only.

```console
$ solari config list
$ solari config set server https://solari.sh
```

- `server · SOLARI_SERVER` — The SOLARI server. Default https://solari.sh.
- `cacheTtl · SOLARI_CACHE_TTL` — Seconds the local tool list counts as fresh. Default 900; 0 always asks the server.
- `callTimeout · SOLARI_CALL_TIMEOUT` — Seconds to wait for a tool call. Default 150.
- `SOLARI_TOKEN` — An access token or API key to use instead of the stored sign-in. See From your own code.
- `SOLARI_HOME` — Stores SOLARI's files somewhere other than ~/.solari.
- `SOLARI_NO_UPDATE_CHECK=1` — Turns off the daily update check.

## Agents

```text
set up solari.sh/get-started.md
```

Give this line to a coding agent and it sets everything up. The install script also registers the CLI with the agents it finds (Claude Code, Codex, Grok Build, Antigravity CLI, OpenCode). It never edits CLAUDE.md or a project's AGENTS.md.

```bash
solari init            # register again, choosing agents
solari init --remove   # undo
```

### Machine-readable docs

Add .md to any docs URL for Markdown (?lang=ko or ?lang=ja for Korean or Japanese). /llms.txt lists every page, and /llms-full.txt has everything in one file.

## From your own code

The same tools are available over a REST API, TypeScript and Python SDKs, and MCP, all with one token. Full reference: https://solari.sh/api

```console
$ solari auth token
```

Prints an access token valid for 8 hours. Keep it secret. For CI, servers, or scheduled jobs, create an API key (solari_sk_…) at https://solari.brandazine.com/me/api-keys instead.

Put either one in SOLARI_TOKEN. The CLI and the SDKs then run without signing in, and HTTP calls send it as a bearer token:

```console
$ export SOLARI_TOKEN=<token or API key>
$ solari catalog instagram account search query=nike --json
$ curl -sS https://solari.sh/mcp/api/v1/tools/solari_catalog_instagram_account_search \
  -H "Authorization: Bearer $SOLARI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"nike","limit":3}'
```

## Errors and exit codes

- `0` — Success.
- `1` — The tool or the server failed.
- `2` — Bad input: an unknown path, a missing argument, or an invalid value.
- `3` — Sign-in required. Only a person can finish it, so an agent should tell the user instead of retrying.

### Common tool errors

- `auth expired, reconnect the connector` — Run solari auth login again, or reconnect the connector in your app.
- `SOLARI access denied (403)` — Sign in again.
- `SOLARI rate limit` — Over your plan's calls per minute. Wait the seconds the message gives.
- `SOLARI upstream timed out` — The call ran past 90 seconds (120 for aggregate and trend-cluster tools). Narrow the range or lower limit.
- `CREDIT_EXHAUSTED` — No credit left, or the trial hasn't started (email or card setup incomplete). Not charged. Don't retry; run solari usage and follow the error.
- `ACCOUNT_BLOCKED` — Tool calls are paused for this account. Not charged; the error says who to contact.

## Data coverage

- content search and content aggregate: KR, JP, US, TW, about the last 6 months.
- Account, brand, and post tools: full history, any region. KR has the most data.
- Counts are exact up to 10,000. TikTok search stops paging at 9,800.

### Identifiers

- account_id and post_id are per platform. Instagram, TikTok, and Threads ids don't mix.
- Pass account_id or username. If both are set, account_id wins.
- Public post ids: slug on Instagram, video_id on TikTok, code on Threads.

## FAQ

### Can I change SOLARI data?

No. SOLARI data can't be edited or deleted. The fetch tools only collect public accounts and posts.

### Can I use this with Claude?

Yes. Run solari init to register the CLI with your agents, or connect over MCP.

### Why does search return 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.

### Does it cost anything?

Tool calls use prepaid credits, and only successful calls use them. A new account with a verified email can start a one-time 30-day trial with 5,000 credits after card setup. Nothing is charged, and no paid plan starts on its own. Plans and prices: https://solari.sh/pricing

## Connect over MCP

- [Connect over MCP](https://clip-pub.bzine.co/docs/mcp.md)

## Tool reference

- [Tool reference](https://clip-pub.bzine.co/docs/tools.md)