가이드

개요

SOLARI CLI·MCP로 SOLARI가 모은 Instagram, TikTok, Threads 데이터를 터미널, 스크립트, AI 에이전트에서 쓸 수 있습니다. 도구는 세 묶음입니다:

• catalog: SOLARI에 이미 있는 계정과 게시물.
• insight: 순위, 비슷한 계정, 광고, 트렌드처럼 SOLARI가 계산한 결과.
• fetch: 플랫폼에서 바로 수집하는 계정, 게시물, Instagram 해시태그.

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

터미널이나 명령을 실행하는 에이전트에서는 CLI를, Claude Desktop·ChatGPT 같은 앱에서는 MCP를 쓰세요.

설치

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

$ solari --version
1.0.1

빠른 시작

$ 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

결과로 받은 username이나 account_id를 다음 도구에 넣으세요:

$ solari insight instagram brand ad stats username=innisfreeofficial

명령 구조

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

인자는 key=value 쌍입니다. 배열은 JSON이나 쉼표 목록(post_ids=a,b)으로 넣습니다.

solari help all

모든 명령·도구·파라미터를 한 페이지로 보여 줍니다. 최근 7일 안에 추가된 도구에는 NEW가 붙습니다.

solari get <path ...>

도구 실행만 합니다. 경로가 덜 끝나면 목록 대신 실패합니다.

solari cache refresh

도구 목록을 바로 다시 받고, 바뀐 도구를 보여 줍니다.

인증

solari auth login

브라우저로 로그인합니다. SSH나 에이전트 환경에서는 링크를 대신 출력합니다. --add를 붙이면 다른 계정도 추가로 로그인합니다.

solari auth list · switch <account>

로그인해 둔 계정을 보거나, 브라우저 없이 계정을 바꿉니다.

solari auth status

계정과 로그인 만료 시각을 보여 줍니다. 종료 코드 3이면 다시 로그인해야 합니다.

solari auth logout

로그아웃합니다. --all은 모든 계정에서 로그아웃합니다.

브라우저가 CLI를 실행한 컴퓨터로 돌아갈 수 없으면(SSH, 컨테이너) 로그인 후 주소창의 URL을 복사해 프롬프트에 붙여 넣으세요.

크레딧과 사용량

성공한 도구 호출만 크레딧을 차감합니다. 크레딧은 계정의 선불 잔액에서 빠지고 CLI, MCP, REST API가 이 잔액을 같이 쓰며, 여러 페이지로 나뉜 결과는 페이지마다 따로 호출한 것으로 셉니다. 실패한 호출, 도구 목록, 앱 카탈로그, 계정 정보, 피드백, 잔액 확인은 무료입니다.

$ solari usage

플랜, 남은 크레딧과 만료일, 최근 30일 과금 호출 수를 보여 줍니다. 무료이고 잔액이 0이어도 동작합니다. MCP에서는 solari_usage_get을 쓰세요.

잔액이 0이면 호출이 CREDIT_EXHAUSTED(REST: HTTP 402)로 실패하고, 차감되지 않습니다. 다음에 할 일은 오류 메시지에 나옵니다.

플랜·체험·추가 크레딧: https://solari.sh/pricing · 내 잔액: https://solari.brandazine.com/settings/billing

출력과 파이프

결과는 표준 출력, 안내는 표준 에러로 나가서 파이프에는 데이터만 넘어갑니다.

--json

가공하지 않은 JSON. 데이터는 content[0].text 안의 JSON 문자열입니다.

--ndjson

한 줄에 JSON 객체 하나. total 같은 값은 표준 에러로 나갑니다.

--verbose, -v

진행 상황을 표준 에러로 출력합니다. 비밀 값은 가립니다.

게시물마다 assets에 미디어 파일이 순서대로 들어 있고, 각 asset_url로 바로 내려받을 수 있습니다. 저장된 사본이므로, 최고 화질은 solari instagram download content나 solari tiktok download content로 받으세요.

$ 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

에이전트 피드백

에이전트가 SOLARI로 작업을 끝낼 수 없으면(데이터나 기능이 없음, 결과 부족, 틀린 값, 계속 실패하는 도구) 묻지 않고 SOLARI 팀에 피드백을 보내고 한 줄로 알려 줍니다. 개인정보는 빼고 보내며, SOLARI가 저장 전에 이메일, 전화번호, 키를 한 번 더 지웁니다.

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

설정

설정은 ~/.solari/config.json에 저장됩니다. 환경변수를 주면 그 명령에서만 설정보다 우선합니다.

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

server · SOLARI_SERVER

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

cacheTtl · SOLARI_CACHE_TTL

로컬 도구 목록을 최신으로 보는 시간(초). 기본 900이고, 0이면 매번 서버에 묻습니다.

callTimeout · SOLARI_CALL_TIMEOUT

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

SOLARI_TOKEN

저장된 로그인 대신 쓸 액세스 토큰이나 API key. '내 코드에서 쓰기'를 참고하세요.

SOLARI_HOME

SOLARI 파일을 ~/.solari 대신 다른 곳에 저장합니다.

SOLARI_NO_UPDATE_CHECK=1

하루 한 번 하는 업데이트 확인을 끕니다.

에이전트

set up solari.sh/get-started.md

코딩 에이전트에 위 한 줄을 주면 설정을 끝냅니다. 설치 스크립트도 이 컴퓨터에서 찾은 에이전트(Claude Code, Codex, Grok Build, Antigravity CLI, OpenCode)에 CLI를 등록합니다. CLAUDE.md나 프로젝트의 AGENTS.md는 건드리지 않습니다.

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

에이전트용 문서

문서 주소 뒤에 .md를 붙이면 마크다운으로 받습니다(?lang=ko·?lang=ja로 언어 선택). /llms.txt는 전체 색인, /llms-full.txt는 전체 문서 한 파일입니다.

내 코드에서 쓰기

같은 도구를 REST API, TypeScript·Python SDK, MCP로도 쓸 수 있고, 토큰 하나로 모두 씁니다. 전체 레퍼런스: https://solari.sh/api

$ solari auth token

8시간 동안 유효한 액세스 토큰을 출력합니다. 비밀로 관리하세요. CI, 서버, 예약 작업에는 https://solari.brandazine.com/me/api-keys 에서 API key(solari_sk_…)를 만들어 쓰세요.

둘 중 하나를 SOLARI_TOKEN에 넣으면 CLI와 SDK가 로그인 없이 동작하고, HTTP 호출은 bearer 토큰으로 보냅니다:

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

오류와 종료 코드

0

성공.

1

도구나 서버 쪽에서 실패했습니다.

2

잘못된 입력입니다. 없는 경로, 빠진 인자, 잘못된 값 중 하나입니다.

3

로그인이 필요합니다. 사람만 끝낼 수 있으니 에이전트는 다시 시도하지 말고 사용자에게 알려야 합니다.

자주 보는 도구 오류

auth expired, reconnect the connector

solari auth login을 다시 실행하거나, 앱에서 커넥터를 다시 연결하세요.

SOLARI access denied (403)

다시 로그인하세요.

SOLARI rate limit

요금제의 분당 호출 한도를 넘었습니다. 메시지에 나온 초만큼 기다리세요.

SOLARI upstream timed out

호출이 90초(집계·트렌드 묶음 도구는 120초)를 넘겼습니다. 범위를 좁히거나 limit을 낮추세요.

CREDIT_EXHAUSTED

크레딧이 없거나, 이메일 인증·카드 등록이 끝나지 않아 체험이 시작되지 않았습니다. 차감되지 않습니다. 다시 시도하지 말고 solari usage로 확인한 뒤 오류 메시지를 따르세요.

ACCOUNT_BLOCKED

이 계정의 도구 호출이 일시 중지됐습니다. 차감되지 않았고, 문의할 곳은 오류 메시지에 나옵니다.

데이터 범위

• content search·content aggregate: KR·JP·US·TW, 대략 최근 6개월.
• 계정·브랜드·게시물 도구: 전체 이력, 지역 제한 없음. KR 데이터가 가장 많습니다.
• 건수는 10,000까지 정확합니다. TikTok 검색은 9,800건까지만 페이지를 넘길 수 있습니다.

식별자

• account_id와 post_id는 플랫폼마다 다릅니다. Instagram, TikTok, Threads id는 섞어 쓸 수 없습니다.
• account_id나 username을 넘기세요. 둘 다 있으면 account_id가 우선입니다.
• 공개 게시물 id: Instagram은 slug, TikTok은 video_id, Threads는 code.

자주 묻는 질문

SOLARI 데이터를 수정할 수 있나요?

아니요. SOLARI 데이터는 바꾸거나 지울 수 없습니다. fetch 도구는 공개 계정과 게시물을 수집하기만 합니다.

Claude 같은 에이전트에서도 쓸 수 있나요?

네. solari init으로 에이전트에 CLI를 등록하거나, MCP로 연결하세요.

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

계정 검색은 사용자명이나 표시 이름에 입력한 글자가 그대로 들어 있어야 찾습니다. 콘텐츠 검색은 KR·JP·US·TW 지역과 최근 6개월 안의 날짜로 검색하세요.

요금이 있나요?

도구 호출은 선불 크레딧을 쓰고, 성공한 도구 호출만 크레딧을 차감합니다. 이메일 인증을 마친 새 계정은 카드를 등록하면 30일간 5,000 크레딧을 한 번 체험할 수 있습니다. 청구나 자동 유료 전환은 없습니다. 플랜과 가격: https://solari.sh/pricing