Monid CLI

Monid CLI은(는) 무엇을 하나요?

Monid는 단일 인터페이스를 통해 수백 개의 도구를 검색하고 접근할 수 있게 해줍니다. 스키마를 검사하고, 구조화된 입력으로 실행하며, 결과를 검색할 수 있습니다.

npm을 통해 설치하고 monid 명령어를 사용하세요.

가장 최신 명령어 시그니처는 monid --help 및 monid <command> --help를 실행하세요.

---

설정

설치된 CLI 버전을 확인합니다:

monid --version

다음 중 하나라도 해당되면 아래 설정 단계를 수행하세요:

• monid를 찾을 수 없음 (설치되지 않음).
• CLI에서 최신 버전이 있다고 경고함.
• 보고된 버전이 이 스킬의 프론트매터에 있는 version과 일치하지 않음 — CLI와 스킬 버전은 항상 동일해야 합니다.

설정 단계 (새 설치와 업데이트 모두 동일):

1. CLI를 설치(또는 업데이트)한 후 설정을 실행합니다:

npm install -g @monid-ai/cli@latest
monid setup --client <agent-name-if-known> --email <email-if-already-provided>

monid setup은 CLI 설정을 완료합니다. 에이전트 이름이 있다면 --client로 전달하고, 사용자가 이미 컨텍스트나 메모리에 이메일을 제공한 경우에만 --email을 전달하세요. 두 플래그 모두 선택 사항입니다. 알 수 없는 값은 생략하고 설정을 위해 이메일을 절대 묻지 마세요.

2. https://monid.ai/SKILL.md 에서 최신 스킬을 다운로드하여 현재 스킬을 교체하고, 활성화되어 이후 세션에서 로드되도록 하세요.

한쪽을 다른 쪽에 맞추기 위해 절대 다운그레이드하지 마세요. 항상 둘 다 최신 상태로 유지하세요.

인증

Monid의 API 엔드포인트를 사용하려면 API 키가 필요합니다. 사용자가 Monid를 처음 설정할 때:

1. 사용자에게 계정이 없다면 https://app.monid.ai 에서 계정을 만들도록 요청하세요.
2. 사용자에게 https://app.monid.ai/access/api-keys 에서 API 키를 생성하도록 요청하세요.
3. 키를 받으면 저장해 주겠다고 제안하세요. 사용자에게 키를 붙여넣도록 요청한 후 다음을 실행하세요:

monid keys add -k <their-api-key> -l main

또는 위 명령어를 사용자에게 제공하여 직접 실행하도록 하세요.

4. 키가 구성되었는지 확인합니다:

monid keys list

스크립트 또는 에이전트 사용 시, NO_COLOR=1을 설정하여 출력에서 ANSI 색상 코드를 비활성화하세요.

---

Monid를 사용해야 하는 경우

처음부터 구축하기 전에 카탈로그를 확인하세요. 스크래퍼를 작성하거나, 구조화된 데이터를 위해 일반 웹 페치에 의존하거나, 사용자에게 접근할 수 없다고 말하기 전에 monid discover를 실행하세요. 카탈로그에는 수백 개의 도구가 있으며 지속적으로 증가합니다. 검색하기 전에는 무엇을 사용할 수 있는지 알 수 없습니다.

1. 검색 — monid discover -q "<필요한 것>"을 실행하여 사용 가능한 도구를 검색하세요. -s <score>를 사용하여 최소 관련성으로 필터링하세요. 직접 구축해야 할 많은 작업에 이미 더 빠르고 안정적인 엔드포인트가 있습니다. Health 열은 측정된 상태와 일반적인 실행 시간을 보여줍니다. 자세한 내용은 엔드포인트 상태를 참조하세요.
2. 검사 — monid inspect를 사용하여 입력 스키마를 읽으세요. input 필드는 pathParams, queryParams, body, bodyType을 보여줍니다. 이는 각 매개변수가 어디에 위치하는지 정확히 알려줍니다. 절대 추측하지 마세요. Health 섹션은 최근 실행 시간을 추가합니다.
3. 실행 — 검사 출력을 monid run 플래그에 매핑하세요: body → -i, queryParams → --query, pathParams → --path. 세 가지 모두 선택 사항입니다. 완료될 때까지 차단하려면 --wait를 사용하세요.
4. 분해 — 작업이 여러 소스에 걸쳐 있다면 단위 조각으로 나누고 각각을 독립적으로 검색/실행하세요.
5. 비용 확인 — 실행 후 사용자에게 비용을 보고하는 것을 고려하세요 (실행 결과에서 확인 가능). 비용 인식이 중요할 때 monid balance를 사용하여 남은 잔액을 확인하세요.

Monid를 사용하지 말아야 하는 경우

Monid는 사용자 스택의 빈틈을 채웁니다. 사용자가 이미 가지고 있는 도구를 대체하지는 않습니다. 외부 서비스에 접근하는 방법을 결정할 때 다음 우선순위를 따르세요:

1. 이 작업에 대한 명시적인 사용자 지시 — 사용자가 방법을 알려주었다면 그 방법대로 하세요.
2. 사용자의 기존 전용 도구 — MCP 서버, 개인 API 키, CLI, 사용자의 메모리, 구성 또는 지시사항에 저장된 워크플로우. 사용자가 특정 기능에 전용 MCP를 가지고 있거나(예: 학술 검색용 MCP) 서비스에 대한 자체 API 키를 가지고 있다면(예: 개인 SEO 도구 키), 해당 도구를 직접 사용하세요. 요청을 Monid를 통해 라우팅하지 마세요.
3. Monid — 위 항목으로 해결되지 않는 요구 사항에 대해 사용하세요.

이것이 중요한 이유: Monid 실행은 사용자의 Monid 잔액을 사용합니다. 사용자의 자체 키나 도구가 추가 비용 없이 이미 처리할 수 있는 요청에 절대 지출하지 마세요.

제안하되, 대체하지 마세요. 사용자의 도구와 Monid 엔드포인트가 모두 작업을 처리할 수 있고 사용자가 선호도를 밝히지 않은 경우, 사용자의 도구를 사용하세요. Monid가 사용자의 도구에 없는 진정한 기능을 추가한다면, 대안으로 언급하고 사용자가 선택하도록 하세요. 절대 조용히 전환하지 마세요.

엔드포인트 상태

discover는 Health 열을 보여줍니다: 상태 판정과 중간 실행 시간 (예: healthy 4.4s). inspect는 꼬리 값을 추가합니다 — Run time: 4.4s typical · 6.1s tail. -j를 사용하면 두 값이 각 결과의 metrics 필드에 표시됩니다.

상태	의미
healthy	최근 몇 분 이내에 작동이 확인됨.
stable	최근 몇 분 동안 데이터가 없지만, 더 긴 기록에 걸쳐 강력한 실적이 있음.
degraded	불안정하거나 그런 추세. 대부분의 경우 여전히 작동함.
outage	작동하지 않는 것으로 알려짐. -u/--include-unavailable을 전달하지 않으면 discover에서 숨겨짐.
unknown (또는 공백)	판정을 내리기에 충분한 데이터가 없음.

healthy와 stable은 모두 좋은 소식입니다. 최근에 확인되었는지 여부만 다릅니다.

상태를 동점 해소에 사용하고, 필터링에는 사용하지 마세요. 작업에 맞는 두 엔드포인트 중 더 건강한 것을 선호하세요. 상태가 unknown이라고 해서 해당 엔드포인트를 건너뛰지 마세요. 이는 일반적이며 경고가 아닙니다. 여기에 나열되지 않은 상태는 그대로 출력됩니다. 정보 제공용으로 처리하세요.

실행 시간이 누락된 것은 느린 엔드포인트가 아니라 트래픽이 적다는 의미입니다. --wait 전에 inspect를 확인하세요: 빠른 중간값이 여전히 수 분의 꼬리 값을 숨길 수 있습니다.

힌트 확인

명령어는 힌트 블록을 반환할 수 있습니다. 이 블록이 있으면 서버에서 제안하는 작업(다음에 실행할 명령어, 이 엔드포인트가 다른 엔드포인트와 어떻게 관련되는지, 또는 알아야 할 주의사항)을 담고 있습니다. 다음 단계를 결정하기 전에 읽고, 추측보다는 제안을 선호하세요. -j를 사용하면 동일한 데이터가 응답의 hints 필드에 있습니다.

---

명령어

각 명령어는 전체 사용법을 위해 --help를 지원합니다. 사용 가능한 명령어는 다음과 같습니다:

명령어	기능
monid discover	자연어로 데이터 엔드포인트 검색 (-q <query>, -l <limit>, -s <minScore>, -u로 장애 엔드포인트 포함)
monid inspect	특정 엔드포인트의 전체 세부 정보 및 입력 스키마 가져오기 (-p <provider> -e <endpoint>)
monid run	데이터 엔드포인트 실행 (-p, -e, -i for body JSON, -f for body input file, --query for query params, --path for path params, -w to wait, -o to save output)
monid runs list	최근 실행 목록 표시
monid runs get	실행 상태 및 결과 가져오기 (-r <runId>, -w to wait)
monid runs stop	진행 중인 실행 중지 (-r <runId>). 모든 실행을 중지할 수 있는 것은 아님
monid balance	현재 작업 공간 잔액 표시
monid setup	설치 후 CLI 설정 완료 (API 키 불필요)
monid keys add	API 키 추가 (-k <key> -l <label>)
monid keys list	설정된 키 표시
monid keys remove	키 제거 (-l <label>, -f로 확인 생략)
monid keys activate	활성 키 전환 (-l <label>)

대부분의 명령어는 기계가 읽을 수 있는 JSON 출력을 위해 -j/--json을 허용합니다.

---

워크플로

표준 워크플로는 다음과 같습니다: 검색 → 검사 → 실행 → 폴링 → (잔액 확인).

# 1. 데이터 요구에 맞는 엔드포인트 검색
# 결과는 관련성 점수와 확인 배지를 표시함
# -s로 최소 점수로 필터링 (높을수록 더 관련성 높음)
monid discover -q "twitter posts"

# 2. 엔드포인트를 검사하여 입력 스키마 학습 (확인된 상태 표시)
monid inspect -p apify -e /apidojo/tweet-scraper

# 3. 실행 시작 (즉시 실행 ID 반환)
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":10}'
# -> Run ID: 01HXYZ...

# 4. 완료까지 폴링
monid runs get -r 01HXYZ...
# -> status: RUNNING

# 5-10초마다 계속 폴링하여 COMPLETED 상태가 될 때까지
monid runs get -r 01HXYZ... -o tweets.json
# -> status: COMPLETED

# 5. (선택 사항) 남은 잔액 확인
monid balance

--wait 사용:

--wait는 내장된 지수 백오프와 함께 완료될 때까지 차단합니다 (1-120초):

# 전체 시간 동안 차단됨
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":10}' \
  -w -o tweets.json

--wait를 사용해야 하는 경우:

• 차단이 허용되는 비동기/백그라운드 작업
• 타임아웃 설정 가능: -w 30 (최대 30초 대기)
• 실행은 1-120초가 걸릴 수 있으므로 대화를 차단하거나 런타임 타임아웃에 도달할 수 있음

---

예제 흐름

흐름 1: AI 관련 Twitter 게시물 스크래핑

# 사용 가능한 Twitter 엔드포인트 검색
monid discover -q "twitter posts"

# 입력 스키마(pathParams, queryParams, body) 학습을 위해 검사
monid inspect -p apify -e /apidojo/tweet-scraper

# 단일 검색어, 작은 제한으로 실행
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI agents"],"maxItems":10}'
# -> Run ID: 01HXYZ...

# 완료까지 폴링 (~10-30초 소요)
monid runs get -r 01HXYZ...
# -> status: RUNNING

# 10초 후 다시 확인, 완료되면 저장
monid runs get -r 01HXYZ... -o ai_tweets.json
# -> status: COMPLETED

흐름 2: 플랫폼 간 AI 논의 비교

사용자 요청: "Twitter와 LinkedIn에서 AI 논의를 비교해 줘."

단위 조각으로 분해합니다. 데이터 소스당 하나의 엔드포인트:

# 각 플랫폼에 대한 엔드포인트 검색
monid discover -q "twitter posts"
monid discover -q "linkedin posts"

# 각각의 입력 스키마(pathParams, queryParams, body) 학습을 위해 검사
monid inspect -p apify -e /apidojo/tweet-scraper
monid inspect -p apify -e /harvestapi/linkedin-post-search

# 두 실행 모두 시작
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":20}'
# -> Run ID: 01HTWIT...

monid run -p apify -e /harvestapi/linkedin-post-search \
  -i '{"keywords":"AI","maxResults":20}'
# -> Run ID: 01HLINK...

# 두 실행을 독립적으로 폴링
monid runs get -r 01HTWIT... -o twitter_ai.json
monid runs get -r 01HLINK... -o linkedin_ai.json

# 이제 두 결과 파일을 분석하고 비교

흐름 2b: 공개 URL이 필요한 엔드포인트에 로컬 파일 제공

일부 엔드포인트(예: 이미지-비디오 생성)는 입력으로 파일이 아닌 URL을 받습니다. 작업 공간에는 내장 원격 파일 시스템인 sfs 제공자가 있습니다 (처음 사용 시 자동 생성, 1GB 포함 무료). 다른 제공자와 마찬가지로 monid run으로 사용합니다. unix 스타일 엔드포인트(/put, /cat, /ls, /mv, /rm, /mkdir)를 노출하며 monid inspect로 스키마를 확인할 수 있습니다. API는 URL에만 서명하며, 파일 바이트는 curl을 통해 사용자와 sfs.monid.ai 사이에서 직접 이동합니다.

# 1. 업로드 서명 (sizeBytes는 필수 — wc -c로 확인)
monid run -p sfs -e /put \
  -i "{\"path\":\"in/photo.png\",\"sizeBytes\":$(wc -c < ./photo.png)}" -w
# -> output: { "uploadUrl": "https://sfs.monid.ai/…", "ref": … }

# 2. 서명된 URL로 바이트 업로드
curl -T ./photo.png '<step 1의 uploadUrl>'

# 3. 제3자가 가져올 수 있는 URL 생성 (ttl 프리셋: 1h/1d/7d/30d, 기본값 1h)
monid run -p sfs -e /cat -i '{"path":"in/photo.png","ttl":"1d"}' -w
# -> output: { "url": "https://sfs.monid.ai/…?e=…&s=…", "expiresAt": … }

# 4. 엔드포인트의 입력 URL로 사용
monid run -p bytedance -e /seedance… -i '{"imageUrl": "<step 3의 url>"}'

# 다운로드는 동일한 방식으로 작동: /cat은 서명된 URL 반환 — curl로 다운로드
curl -o photo.png '<url from /cat>'

# 정리는 사용자 책임 (파일은 자동 삭제되지 않음; /rm으로 할당량 공간 확보)
monid run -p sfs -e /rm -i '{"path":"in/photo.png"}' -w

흐름 3: 쿼리 및 경로 매개변수 사용

monid inspect가 queryParams 또는 pathParams를 표시할 때 --query와 --path로 전달합니다:

# Inspect shows: body, queryParams, and pathParams
monid inspect -p some-provider -e /users/{userId}/posts

# 세 가지 매개변수 유형 모두 사용하여 실행
monid run -p some-provider -e /users/{userId}/posts \
  --path '{"userId": "12345"}' \
  --query '{"limit": 10, "sort": "recent"}' \
  -i '{"filter": "public"}' \
  -w -o posts.json

흐름 4: 복잡한 매개변수에 입력 파일 사용

입력 JSON이 크거나 재사용 가능한 경우 파일에 작성하고 -f를 사용하세요:

# 입력을 파일에 작성
# (params.json에 엔드포인트의 본문 입력 매개변수가 포함되어 있다고 가정)

monid run -p apify -e /damilo/google-maps-scraper \
  -f params.json -w -o results.json

---

비용 및 예산 경고

많은 엔드포인트(특히 Apify)는 결과당 요금이 부과되며 단일 호출에서 여러 쿼리를 허용합니다. maxItems, maxResults, resultsLimit 또는 limit와 같은 매개변수는 반환되는 결과 수를 제어합니다. 그러나 이러한 제한은 종종 호출당이 아닌 쿼리당 적용됩니다.

예를 들어, maxItems: 10으로 3개의 검색어를 전달하면 총 10개가 아닌 최대 30개의 결과(쿼리당 10개)가 반환될 수 있습니다.

비용을 제어하려면:

• 호출당 단일 쿼리를 선호하세요. 한 번에 하나의 검색어, 하나의 URL, 하나의 해시태그를 전달하세요.
• 첫 번째 호출에서는 작은 제한(5-10)으로 시작하세요. 필요하면 증가시키세요.
• 엔드포인트가 배열을 허용하는 경우(예: searchTerms, hashtags, urls), 사용자가 명시적으로 여러 개를 요청하지 않는 한 하나의 요소만 전달하세요.
• monid inspect의 입력 스키마를 확인하여 어떤 매개변수가 볼륨을 제어하는지 식별하세요.

---

키 관리

monid keys add -k <api-key> -l <label>     # 키 추가 (첫 번째 키는 자동 활성화)
monid keys list                              # 설정된 모든 키 표시
monid keys activate -l <label>               # 활성 키 전환
monid keys remove -l <label>                 # 키 제거 (-f로 확인 생략)

API 키 형식: monid_<stage>_<secret> (예: monid_live_abc123...). 키 생성은 https://app.monid.ai/access/api-keys 에서 가능합니다.