가이드

개요

SOLARI CLI·MCP를 통해, SOLARI가 확보한 Instagram, TikTok, Threads 등의 데이터를 원하는 곳에서 자유자재로 활용할 수 있어요. catalog는 이미 모아 둔 계정·포스트를 찾고, insight는 우리가 만든 순위·유사·광고·트렌드를 주고, fetch는 핸들 하나를 계정이나 포스트로 카탈로그에 넣어요.

$ 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

설치

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

$ solari --version
1.0.0-alpha.9

빠른 시작

$ 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

account_id를 찾은 다음 다른 도구에 넣어요:

$ 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 는 계정이 스스로를 소개한 문구를 찾아요:

$ 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

명령 구조

$ 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

인자는 key=value 쌍이에요. 배열은 JSON이나 쉼표 목록 둘 다 받아요.

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

solari help all

모든 명령·도구·파라미터를 한 페이지에 보여 줘요. --json 을 붙이면 기계가 읽는 형태로 나와요.

solari get <path ...>

도구만 실행해요. 덜 끝난 경로는 목록 대신 실패해요.

solari cache refresh

내 컴퓨터의 도구 목록을 지금 갱신해요.

인증

solari auth login

브라우저를 열어요. 열 수 없는 환경(SSH, 에이전트가 대신 실행하는 경우)에서는 로그인 링크를 대신 출력해요.

solari auth list

로그인해 둔 SOLARI 계정을 모두 보여줘요.

solari auth switch <account>

이미 로그인해 둔 다른 계정으로 전환해요. 브라우저를 다시 열지 않아요.

solari auth status

서버, 계정, 로그인 만료 시각. 종료 코드 3이면 다시 로그인해야 해요.

solari auth logout

로그아웃해요. --all 을 붙이면 모든 계정에서 한 번에 로그아웃해요.

브라우저가 명령을 실행한 컴퓨터로 되돌려주지 못하는 환경(SSH, 컨테이너)에서는, 로그인을 마친 뒤 브라우저 주소창의 주소를 복사해서 기다리고 있는 프롬프트에 붙여넣으면 끝나요.

출력과 파이핑

결과는 표준 출력, 안내는 표준 에러로 나가요. 파이프에는 데이터만 흘러요.

--json

가공하지 않은 JSON. 실제 데이터는 content[0].text 안의 JSON 문자열이에요.

--ndjson

한 줄에 JSON 객체 하나. total 같은 감싼 값은 표준 에러로 가요.

--refresh

로컬 사본을 건너뛰고 서버에서 도구 목록을 받아요.

--verbose, -v

진행 상황을 표준 에러로 찍어요. 비밀 값은 가려져요.

$ 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

설정

설정은 ~/.solari/config.json 에 있어요. 환경변수는 그 한 번의 명령에서만 이겨요.

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

server · SOLARI_SERVER

접속할 SOLARI 서버. 기본값 https://solari.sh.

cacheTtl · SOLARI_CACHE_TTL

내 컴퓨터의 도구 목록을 최신으로 볼 시간(초). 기본 900이고, 0이면 항상 서버에 물어봐요.

cacheShadow · SOLARI_CACHE_SHADOW

내 컴퓨터에서 답한 뒤, 뒤에서 조용히 도구 목록을 갱신할지. 기본 true.

callTimeout · SOLARI_CALL_TIMEOUT

도구 호출을 기다리는 시간(초). 기본 150.

catalogTimeout · SOLARI_CATALOG_TIMEOUT

도구 목록을 기다리는 시간(초). 기본 8.

SOLARI_TOKEN

solari auth token 으로 받은 액세스 토큰. 모든 명령에서 저장된 로그인 대신 쓰여요. '직접 짠 코드에서' 참고.

SOLARI_HOME

SOLARI 파일을 ~/.solari 말고 다른 곳에 두게 해요.

SOLARI_NO_UPDATE_CHECK=1

하루 한 번 도는 업데이트 확인을 완전히 꺼요. NO_UPDATE_NOTIFIER=1 도 같은 효과예요.

에이전트

set up solari.sh/get-started.md

solari init 은 이 컴퓨터의 에이전트에 CLI를 등록해요. solari init --remove 로 되돌릴 수 있어요.

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

터미널·스크립트, 그리고 명령을 직접 실행하는 에이전트에는 CLI를 쓰세요. Claude Desktop이나 ChatGPT처럼 앱이 직접 서버에 붙는 경우에는 MCP를 쓰시면 돼요.

기계가 읽는 문서

아무 주소 뒤에 .md 를 붙이면 마크다운이에요. 레퍼런스 전체를 한 파일로도 받을 수 있어요.

/get-started.md

에이전트 설정 페이지.

/llms.txt

llms.txt 형식으로 정리한 문서 색인.

/llms-full.txt

가이드와 도구 전체를 하나의 마크다운 파일로 이어 붙인 것.

/docs/tools.md

아무 페이지나 마크다운으로. ?lang=ko 나 ?lang=ja 를 붙이면 다른 언어로 받아요.

직접 짠 코드에서

CLI 가 실행하는 읽기 전용 도구가 그대로 REST API(https://solari.sh/mcp/api/v1)로도 열려 있어요. 그 위에 공식 TypeScript·Python SDK 가 있고, 에이전트용으로는 MCP 서버가 있어요. 액세스 토큰 하나로 전부 써요.

토큰 받기

$ solari auth token
$ solari auth token --json

로그인한 계정의 액세스 토큰을 출력해요. 만료됐으면 먼저 갱신해요. --json 을 붙이면 만료 시각, 엔드포인트, 계정이 함께 나와요. 토큰은 8시간 유효하고, 그동안 내 SOLARI 계정을 읽을 수 있으니 비밀로 다루세요.

브라우저 없이 CLI 쓰기

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

SOLARI_TOKEN 이 있으면 그 컴퓨터에서는 로그인 없이 모든 명령이 돌아요 — CI, 컨테이너, 브라우저 없는 서버. 이때 CLI 는 ~/.solari/credentials.json 을 건드리지 않고, 도구 캐시도 토큰 기준으로 나눠서 다른 계정의 앱 도구가 섞이지 않아요. 토큰 수명보다 오래 도는 작업이라면 로그인해 둔 ~/.solari 를 (또는 SOLARI_HOME 으로 가리켜) 쓰세요. CLI 가 알아서 갱신해요.

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}'

도구 인자를 JSON 객체로 /tools/<이름> 에 POST 하면 응답이 도구의 JSON 결과예요. GET /tools 는 모든 도구와 입력 스키마를 주고, 오류는 { error: { code, message } } 로 와요. 오류 코드까지 포함한 전체 레퍼런스는 API 페이지에 있어요.

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, 또는 pip install solari-sdk. 둘 다 REST API 를 얇게 감싼 의존성 없는 라이브러리예요. 점으로 이은 경로가 solari_ 접두어 아래 도구 이름으로 합쳐져요.

코드에서 MCP 로

어떤 MCP 클라이언트든 같은 bearer 토큰으로 https://solari.sh/mcp 를 직접 부를 수 있어요. 엔드포인트는 상태가 없어서 initialize 없이 tools/call 한 번으로 끝나요.

오류와 종료 코드

0

성공.

1

도구나 서버 쪽에서 실패했어요.

2

CLI가 받아들일 수 없는 입력이에요. 없는 경로, 빠진 인자, 잘못된 값 중 하나예요.

3

로그인이 필요해요. 브라우저 로그인은 사람만 끝낼 수 있으니까, 에이전트는 계속 시도하지 말고 사용자에게 알려야 해요.

자주 보는 도구 오류

auth expired, reconnect the connector

로그인이 만료됐어요. solari auth login 을 다시 실행하거나, 앱에서 커넥터를 다시 연결해 주세요.

SOLARI access denied (403)

SOLARI가 호출을 거절했어요. 다시 로그인해 보세요.

rate limited, retry shortly

짧은 시간에 너무 많이 불렀어요. 잠깐 쉬었다 다시 시도해 주세요.

SOLARI upstream timed out

호출이 너무 오래 걸렸어요. 대부분의 도구는 90초, 집계와 트렌드 클러스터 도구는 120초예요. 범위를 좁히거나 limit 을 낮춰서 다시 시도해 보세요.

데이터 커버리지

• content search·content aggregate: KR·JP·US·TW, 대략 최근 6개월.
• 계정·브랜드·포스트 도구: 전체 이력, 리전 제한 없음.
• 리전 중에서는 KR의 커버리지가 가장 깊어요.
• 개수는 10,000까지 정확해요. TikTok 검색은 9,800에서 페이지가 멈춰요.

식별자

• account_id 는 플랫폼마다 달라요. Instagram과 TikTok id는 서로 바꿔 쓸 수 없어요.
• account_id 또는 username. 둘 다 있으면 account_id 가 이겨요.
• post_id 도 플랫폼마다 달라요. 공개 id는 slug(Instagram) 또는 video_id(TikTok)예요.

자주 묻는 질문

SOLARI 데이터를 바꾸고 싶어요.

아니요. 모든 도구가 읽기 전용이에요.

Claude 같은 에이전트에서도 쓰고 싶어요.

네. solari init 으로 이 컴퓨터의 에이전트에게 CLI를 알려주거나, MCP 서버에 직접 연결하시면 돼요.

검색 결과가 없다고 나와요.

계정 검색은 사용자명·표시 이름에 그 글자가 있어야 해요. 콘텐츠 검색은 KR·JP·US·TW, 최근 6개월이에요.

요금이 궁금해요.

지금은 무료로 쓰실 수 있어요. 달라지는 게 있으면 미리 안내해 드릴게요.