WidgetStore CLI: 다른 AI 에이전트가 위젯스토어 다루기

%BRAND% 데스크톱 앱에는 명령줄 도구 widgetstore가 들어 있어요. 다른 AI 에이전트(Claude Code, Codex, Gemini CLI, Cursor 등)와 스크립트가 이걸로 %BRAND%를 다룰 수 있어요.

• 클라우드 기능(MCP 서버와 같은 도구): 내 스페이스 확인, 위젯 변경, 내 데이터에 기록 추가, 할 일 추가, 집중 기록, AI로 스페이스 만들기 등. 웹사이트에 새 기능이 생기면 명령에도 자동으로 나타나요.
• 이 컴퓨터 기능: 집중 타이머 시작·종료, 위젯을 데스크톱에 고정, 페이지나 런처 열기, 알림 보내기, AI 사용량 읽기, 로컬 에이전트에게 작업 맡기기.

설치

데스크톱 앱 사이드바 에이전트 → ‘명령줄’ → 명령줄 도구 설치:

• macOS: /usr/local/bin/widgetstore에 연결해요(비밀번호를 물어봐요). 취소하면 ~/.local/bin에 두고 PATH에 추가하는 방법을 알려 줘요.
• Windows: 앱 폴더를 사용자 PATH에 추가해요(관리자 권한 필요 없음). 새 터미널부터 쓸 수 있어요.
• Linux: .deb / .rpm으로 설치했다면 이미 /usr/bin/widgetstore가 있어요. AppImage는 ~/.local/bin/widgetstore로 연결해요.

새 터미널에서 widgetstore status를 실행해 확인하세요.

로그인

• 데스크톱 앱이 있는 컴퓨터(추천): ‘명령줄’에서 계정 연결을 누르고 브라우저에서 줄 권한을 확인해요(필요 없는 건 뺄 수 있어요). 승인은 시스템 키체인(Linux는 본인만 읽을 수 있는 파일)에 저장되고 명령줄 프로세스는 토큰을 볼 수 없어요. 호출은 데스크톱 앱이 대신해요. 웹사이트 ‘설정 → API 및 AI 연결 → 연결된 AI 앱’에서 언제든 해제할 수 있어요.
• 데스크톱 앱이 없는 곳(서버 / CI): 웹사이트에서 개인 토큰을 만들어 WIDGETSTORE_TOKEN=wsp_…로 설정하거나 widgetstore login --token -(표준 입력에서 읽어 키체인에 저장)을 쓰세요.

사용법

widgetstore tools                    # 모든 명령 (클라우드 + 이 컴퓨터)
widgetstore get_my_space --json      # 기계가 읽는 출력
widgetstore add_record --help        # 명령의 옵션
widgetstore focus_start --minutes 25 --task "주간 보고"
widgetstore ask claude "최근 커밋으로 릴리스 노트를 써 줘" --cwd ~/code/app --wait
widgetstore mcp                      # 로컬 MCP 서버 (stdio)

• 옵션은 각 도구의 JSON 스키마에서 만들어져요: --이름 값, --플래그 / --no-플래그, 배열은 같은 옵션을 반복, --args '{"…":…}'로 한꺼번에. 값에 @파일이나 @-(표준 입력)도 쓸 수 있어요.
• --json 출력 형식은 고정이에요: 성공은 {"ok":true,"tool":…,"data":…,"text":…}, 실패는 {"ok":false,"error":{"code","message","exit"}}.
• 종료 코드: 0 성공 · 1 도구나 서버 오류 · 2 사용법 오류 · 3 로그인 안 됨 또는 권한 부족 · 4 데스크톱 앱이 실행 중이 아님(로컬 명령) · 5 데스크톱 앱에서 거부함.

에이전트에 추가하기

widgetstore mcp를 로컬 MCP 서버(같은 도구)로 한 줄이면 추가할 수 있어요:

에이전트	명령 / 설정
Claude Code	claude mcp add widgetstore -- widgetstore mcp
Codex CLI	codex mcp add widgetstore -- widgetstore mcp
Gemini CLI	gemini mcp add widgetstore widgetstore mcp
Cursor	~/.cursor/mcp.json: {"mcpServers":{"widgetstore":{"command":"widgetstore","args":["mcp"]}}}
opencode	opencode.json: {"mcp":{"widgetstore":{"type":"local","command":["widgetstore","mcp"]}}}

MCP 없이 프로젝트의 AGENTS.md / CLAUDE.md에 적어 둘 수도 있어요(‘명령줄’ 화면에 복사 버튼이 있어요):

## WidgetStore
- The `widgetstore` CLI is installed. Run `widgetstore tools --json` to see every command and its JSON schema.
- Call a tool with `widgetstore <tool> --option value --json` (exit code 0 = ok).
- Local actions (opening pages, pinning widgets, agent tasks) need the user to confirm in the WidgetStore desktop app. Cloud writes are logged and can be undone with `widgetstore undo`.

안전

• 권한은 서버에서 토큰 범위에 따라 판단하고, 모든 변경은 작업 기록에 남아 되돌릴 수 있어요(widgetstore undo). 데이터를 지우거나 계정을 바꾸거나 결제하는 명령은 없어요. 불꽃을 쓰는 도구는 명령줄에서 기본으로 꺼져 있어요(‘명령줄’ → 안전에서 켤 수 있어요).
• 이 컴퓨터용 명령은 로컬 통로를 써서 같은 OS 사용자만 연결할 수 있고, 데스크톱 앱이 실행될 때마다 만드는 무작위 암호도 필요해요.
• 페이지나 런처 열기, 위젯 고정, 에이전트 작업 시작은 데스크톱 앱에 확인 창이 뜨고 ‘허용’을 눌러야만 진행돼요. ‘명령줄’ → 안전에서 여는 요청과 읽기 전용 에이전트 작업을 신뢰할 수 있어요. 파일을 편집하거나 ‘모두 자동 승인’인 작업은 항상 물어요.
• 명령줄 프로세스는 로그인 정보와 토큰을 볼 수 없고, 데스크톱 앱이 에이전트를 실행할 때도 넘기지 않아요.