레퍼런스개발자 레퍼런스
CLI (명령줄 도구)
터미널에서 슈츠 워크스페이스를 관리하는 CLI 도구. AI 코딩 에이전트(Claude Code, Codex, Moltbot)와의 통합에 최적화.
CLI란?
슈츠 CLI(suits)는 터미널에서 워크스페이스 데이터를 관리하는 명령줄 도구입니다.
- MCP 설정 없이 Bash 명령어로 바로 슈츠 데이터 접근
- AI 코딩 에이전트 (Claude Code, Codex, Moltbot 등) 최적화
--json출력으로 프로그래밍 활용 가능--quiet출력으로 쉘 스크립트 파이핑 지원
설치
# npm
npm install -g @suits-work/cli
# bun
bun add -g @suits-work/cli
# 설치 없이 바로 실행
npx @suits-work/cli --help설치 후 suits 명령어를 사용할 수 있습니다.
인증 설정
방법 1: API Key (추천)
워크스페이스 설정 → 개발자 설정에서 API 키를 발급받은 후:
suits login --api-key tk_your_api_key --name "마케팅팀"방법 2: 환경변수 (CI/CD용)
export SUITS_API_KEY=tk_your_api_key
suits blocks list방법 3: OAuth 브라우저 로그인
suits login --workspace <workspaceId>
# → 브라우저가 열리고 Google 로그인 후 자동 완료인증 상태 확인
suits whoami인증 우선순위
--api-key플래그 (최우선)SUITS_API_KEY환경변수~/.suits/credentials.json저장된 키
멀티 워크스페이스
여러 워크스페이스를 등록하고 전환할 수 있습니다:
# 워크스페이스 추가
suits login --api-key tk_key1 --name "마케팅팀"
suits login --api-key tk_key2 --name "개발팀"
# 워크스페이스 전환
suits use "개발팀"
# 일회성으로 다른 워크스페이스 사용
suits blocks list --workspace "마케팅팀"명령어 레퍼런스
인증
| 명령어 | 설명 |
|---|---|
suits login --api-key <key> [--name <name>] | API 키로 로그인 |
suits login --workspace <id> | OAuth 브라우저 로그인 |
suits logout | 로그아웃 |
suits whoami | 현재 인증 상태 |
suits use <name> | 활성 워크스페이스 전환 |
블록 (Blocks)
# 블록 목록 조회
suits blocks list [--parent <id>] [--type <type>] [--search <query>] [--limit <n>]
# 블록 상세 조회
suits blocks get <blockId>
# 블록 생성
suits blocks create --type <type> --title <title> [--parent <id>]
# 블록 수정
suits blocks update <blockId> --title <title>
# 블록 삭제
suits blocks delete <blockId> --confirm데이터모델 (DataModels)
# 목록 조회
suits datamodels list [--search <query>] [--limit <n>]
# 상세 조회
suits datamodels get <dataModelId>
# 생성
suits datamodels create --title <title> [--description <desc>]
# 수정
suits datamodels update <dataModelId> --title <title>
# 삭제
suits datamodels delete <dataModelId> --confirm행 (Rows)
# 행 목록
suits rows list <dataModelId> [--limit <n>] [--offset <n>]
# 행 생성
suits rows create <dataModelId> --data '{"field": "value"}'
# 행 수정
suits rows update <dataModelId> <rowId> --data '{"field": "new_value"}'
# 행 삭제
suits rows delete <dataModelId> <rowId> --confirm통계 (Stats)
# 통계 목록
suits stats list [--enabled-only]
# 통계 상세
suits stats get <statId>
# 통계 실행
suits stats run <statId> [--start <date>] [--end <date>] [--timezone <tz>]워크플로우 (Workflows)
# 워크플로우 목록
suits workflows list [--status <status>]
# 워크플로우 상세
suits workflows get <workflowId>
# 워크플로우 실행
suits workflows run <workflowId> [--data '{"key": "value"}']
# 워크플로우 배포
suits workflows deploy <workflowId>워크스페이스 (Workspace)
# 워크스페이스 요약
suits workspace summary글로벌 옵션
모든 명령어에 적용 가능한 옵션:
| 옵션 | 설명 |
|---|---|
--json | JSON 원본 출력 (AI 에이전트용) |
-q, --quiet | 최소 출력 (ID만, 스크립팅용) |
--workspace <name> | 활성 워크스페이스 임시 변경 |
--api-key <key> | 저장된 키 대신 사용 |
출력 형식
기본 (테이블)
ID TYPE TITLE UPDATED
d5e7d4fa-781e-4d02-a262-6761a4a0f877 page 매출 보고서 2026-02-08
1f8eb0cf-152e-4836-8639-60b6b603a164 page 팀 핸드북 2026-02-07
2 blocks found--json (AI 에이전트용)
{
"data": [...],
"meta": { "total": 2, "limit": 20, "offset": 0, "hasMore": false }
}--quiet (파이핑용)
d5e7d4fa-781e-4d02-a262-6761a4a0f877
1f8eb0cf-152e-4836-8639-60b6b603a164AI 에이전트 활용 예시
Claude Code
Claude Code에서 슈츠 데이터를 조회하고 활용하는 시나리오:
# 데이터모델 목록 확인
suits datamodels list --json
# 특정 데이터모델의 행 데이터 가져오기
suits rows list <dataModelId> --json --limit 100
# 새 행 추가
suits rows create <dataModelId> --data '{"title": "새 항목", "status": "진행중"}'Codex / Moltbot
# 워크스페이스 요약 파악
suits workspace summary --json
# 블록 검색
suits blocks list --search "매출" --jsonAI 에이전트에서 사용할 때는 항상 --json 플래그를 추가하세요. 구조화된 JSON 응답으로 파싱이 훨씬 쉬워집니다.
CLI vs MCP vs REST API
| CLI | MCP | REST API | |
|---|---|---|---|
| 설정 | suits login 한 번 | .mcp.json + OAuth | HTTP 헤더마다 |
| AI 에이전트 | Bash로 바로 | MCP 클라이언트 필요 | curl/fetch |
| 출력 형식 | 테이블/JSON/Quiet | 구조화된 JSON | JSON |
| 가장 적합 | 코딩 에이전트, 스크립트 | Claude Desktop, Cursor | 커스텀 앱 개발 |
| 인증 | API Key / OAuth | OAuth 자동 | API Key |
문제 해결
401 Unauthorized
API 키가 유효하지 않거나 만료되었습니다.
# 인증 상태 확인
suits whoami
# 재로그인
suits login --api-key tk_new_key403 Forbidden
API 키의 권한 범위가 부족합니다. 워크스페이스 설정에서 API 키의 스코프를 확인하세요.
429 Rate Limited
요청 제한을 초과했습니다. 잠시 후 다시 시도하세요.