가이드

개요

SOLARI CLI는 SOLARI의 크리에이터·콘텐츠 데이터를 터미널로 가져와요. Instagram·TikTok의 브랜드나 크리에이터를 찾고, 광고 콘텐츠 규모를 재고, 캡션과 영상 전사문에 실제로 담긴 말을 검색하고, 지금 뜨는 흐름을 읽어요. jq·셸 스크립트·AI 코딩 에이전트와 그대로 조합되는 평범한 명령이에요.

SOLARI는 MCP 서버로도 열려 있어서, Claude Desktop이나 ChatGPT 같은 앱은 CLI 없이 바로 닿을 수 있어요. 어느 쪽으로 오든 같은 도구와 같은 읽기 전용 권한을 써요.

$ 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

설치

CLI는 파일 하나예요. 곁들여 깔아야 하는 게 따로 없어요. 평소 도구를 설치하던 방식 중 편한 걸 고르시면 돼요. 어느 쪽이든 받는 건 똑같아요.

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                     # 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

보통은 이름을 account_id 로 바꾼 다음, 그 id 를 다른 도구에 넘기는 순서로 이어져요:

$ 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

이름으로만 들어갈 수 있는 건 아니에요. query_type=bio 는 계정이 스스로를 소개한 문구를 검색하니까, 이미 아는 브랜드가 아니라 카테고리에서 출발할 수 있어요:

$ 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

명령 구조

경로가 곧 명령이에요. 도중까지만 치면 그 아래 있는 것들을 보여주고, 도구 경로를 끝까지 치면 실행되고, 필요한 값을 빠뜨리면 실행하는 대신 무엇이 필요한지 알려줘요. 공백과 밑줄은 똑같이 동작하고, solari_ 접두사는 빼도 돼요.

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

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

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

solari help all

모든 명령·도구·파라미터를 한 페이지에 담아 보여줘요. 내 컴퓨터에서 답하고, --json 을 붙이면 기계가 읽기 좋은 형태로 나와요. AI 에이전트에게 한 번에 전부 쥐여줄 때 좋아요.

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

가공하지 않은 JSON. 도구의 답은 한 겹 감싸여서 와요. 실제 데이터는 content[0].text 안의 JSON 문자열이에요.

--ndjson

한 줄에 JSON 객체 하나씩, 응답 안의 항목을 하나씩 흘려요. 그것들을 감싸고 있던 값(total, has_more 등)은 표준 에러로 가요. jq와 함께 쓰거나, 많은 양을 파일로 바로 받아 적을 때를 위한 옵션이에요.

--refresh

내 컴퓨터의 사본을 건너뛰고 서버에서 도구 목록을 새로 받아요.

--color[=always|never|auto]

도움말과 도구 목록에 색을 입혀요. 기본값 auto 는 터미널에서 볼 때만 색을 써요. NO_COLOR=1 이면 끄고, FORCE_COLOR=1 이면 파이프에서도 켜요. --no-color 는 never 와 같아요.

--verbose, -v

명령이 도는 동안 진행 상황을 표준 에러로 찍어요. 비밀 값은 가려져요.

$ 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

설정

설정은 ~/.solari/config.json 에 있어요. 모든 설정에는 짝이 되는 환경변수가 있고, 환경변수를 주면 그 한 번의 명령에서만 그 값이 이겨요. solari config list 는 지금 적용된 값과 그 값이 어디서 왔는지 함께 보여줘요.

$ 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_HOME

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

SOLARI_NO_UPDATE_CHECK=1

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

도구 목록은 내 컴퓨터에서 먼저 답해요. 그래서 훑어보기와 파라미터 확인이 즉시 끝나요. 사본이 위의 시간보다 오래되면 뒤에서 알아서 갱신해요. 사본이 모르는 경로는 그 자리에서 서버에 물어보니까, 서버에 새로 생긴 도구도 바로 쓸 수 있어요.

에이전트

명령을 실행하는 에이전트를 이미 쓰고 계시다면, 이 한 줄만 건네고 이 페이지는 닫으셔도 돼요. 사람이 아니라 에이전트가 읽으라고 쓴 짧은 설정 페이지를 받아서 나머지는 알아서 해요. 연결하거나 설치하고, 로그인을 안내하고, 이 컴퓨터의 도구에 SOLARI를 등록하는 것까지요.

set up solari.sh/get-started.md

이 아래는 그 페이지가 하는 일이에요. 직접 손으로 하고 싶으시다면 이어서 보시면 돼요.

solari init 은 이 컴퓨터의 AI 에이전트에게 이 CLI가 있다는 걸 알려줘요. 그러면 Instagram·TikTok 데이터에 관한 질문이 나올 때 에이전트가 알아서 이걸 집어요. Claude Code용 skill, Codex의 AGENTS.md 안에 직접 관리하는 구역, zsh 탭 자동완성을 설치해요. solari init --remove 로 전부 되돌릴 수 있어요.

solari init            # claude + codex + zsh, with a confirmation for each
solari init claude     # just one target
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 를 붙이면 다른 언어로 받아요.

오류와 종료 코드

오류 메시지는 다음에 뭘 하면 되는지 알려주고, 종료 코드는 스크립트에서 분기해도 될 만큼 안정적이에요.

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 을 낮춰서 다시 시도해 보세요.

데이터 커버리지

SOLARI가 답할 수 있는 범위는 어느 도구를 쓰느냐에 따라 달라져요. 중요한 제한은 둘이에요. 어느 리전을 다루는가, 그리고 얼마나 과거까지 보는가.

• 키워드 검색과 집계(양 플랫폼의 content search·content aggregate)는 KR·JP·US·TW 네 리전을 다루고 최근 약 6개월치를 담아요. 그보다 이전 날짜를 달라고 하면 가장 오래된 날짜로 당겨지고, 실제로 어느 날짜가 쓰였는지 응답이 알려줘요.
• 계정·브랜드·포스트 조회는 전체 이력을 쓰기 때문에, 네 리전이나 6개월 제한을 받지 않아요.
• 리전 중에서는 KR의 커버리지가 가장 깊어요.
• 검색 결과 수는 10,000까지 정확하고 그 위로는 더 올라가지 않아요. TikTok 검색은 9,800에서 더 넘기지 못하니까, 더 깊이 보려면 기간을 좁혀 보세요.

식별자

• account_id 는 플랫폼별로 발급되는 SOLARI 계정 UUID예요. 같은 브랜드라도 Instagram account_id 와 TikTok account_id 는 다른 값이며 서로 바꿔 쓸 수 없어요.
• 계정을 받는 자리는 account_id UUID와 username 둘 다 받고, 둘 다 주면 account_id 가 이겨요.
• post_id 는 역시 플랫폼별로 발급되는 SOLARI 포스트 UUID예요. 공개된 대응물은 slug(Instagram shortcode)나 video_id(TikTok 숫자 id)예요.

자주 묻는 질문

CLI가 SOLARI 데이터를 바꿀 수 있나요?

아니요. 모든 도구가 읽기 전용이에요. CLI에도 MCP 서버에도 쓰기를 하는 기능은 없어요.

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

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

검색이 왜 아무것도 못 찾았나요?

계정 검색은 핸들을 앞에서부터, 표시 이름은 어디에 있든 찾아요. 입력한 말이 둘 중 하나에 실제로 들어 있어야 해서, 별칭이나 줄임말로는 안 찾아져요. 계정이 실제로 쓰는 철자로 다시 시도해 보세요. 콘텐츠 검색이라면 리전이 KR·JP·US·TW 중 하나인지, 날짜가 최근 6개월 안인지 확인해 보세요.

요금이 있나요?

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