official/cli skill
당신은 CLI를 통해 glyph 서버를 제어하는 AI입니다. 이 스킬은 glyph 명령어 표면 전체의 지도이며, --help만으로는 명확하지 않은 규칙들 — 특히 다른 클라이언트와 명령이 충돌하지 않도록 하는 워크스페이스 스코핑 규율과 실패 시 기계적으로 분기할 수 있는 종료 코드/오류 코드 규율 — 에 대한 것입니다.
설정
glyph는 작업 또는 세션을 시작할 때 필요한 환경 변수를 주입합니다:
GLYPH_SERVER— 서버 URL (CLI가 자동으로 사용)GLYPH_WORKSPACE— 워크스페이스 UUID (워크스페이스 범위 명령이 상속)
빠른 확인:
glyph health # 종료 0 ⇒ CLI 작동 + 서버 연결 가능
glyph workspace current --json | jq # 워크스페이스 확인
명령어 표면 개요
모든 워크스페이스 범위 명령은 --server / --workspace-id / --output / --json을 상속하며 아래 공유 종료 코드 표를 따릅니다. 하위 명령 그룹:
| 그룹 | 목적 | 참조 |
|---|---|---|
workspace | 워크스페이스 생성/목록/보기/업데이트/제거/새로고침; 현재 ID 출력 | references/commands.md#workspace |
session | 대화형 세션 관리 (목록/새로 만들기/보기/제거/터미널 실행) | references/commands.md#session |
task | 일회성 작업 전달, 목록 (--origin으로 범위 지정 가능), 검사, 활동 추적, 취소, 제거 | references/commands.md#task |
schedule | Cron 트리거 작업 실행기 (만들기/목록/수정/활성화/비활성화/실행/미리보기/작업 목록) | references/commands.md#schedule |
catalog | 에이전트, 스킬, MCP 설치/동기화/활성화/비활성화 | references/commands.md#catalog |
workflow | 워크플로 시드, 라이브 DAG 읽기/변경 (확장, update-spec으로 not_started 노드 사양 수정), 사람 노드에 응답, 종료 | references/commands.md#workflow |
runtime | 등록된 런타임 목록 (copilot 등) | references/commands.md#runtime |
| 서버 검사 | health, config, status, logs — 수명 주기 없음 | references/commands.md#server-inspection |
| 서버 수명 주기 | serve / start / stop / restart — 이 스킬의 범위 밖 | — |
워크스페이스 규율
모든 워크스페이스 범위 명령은 명시적인 선택자가 필요합니다. CLI는 환경 변수 GLYPH_WORKSPACE(이미 설정됨)를 읽으므로 명령이 그대로 작동합니다:
glyph task dispatch --agent writer --brief "..."
다른 워크스페이스에서 작업하려면 명령마다 --workspace-id <id>를 전달하세요:
glyph task list --workspace-id ws-Y
CLI는 서버 측 공유 "현재 워크스페이스" 상태를 참조하지 않습니다 — 선택자는 프로세스 로컬이므로 다른 클라이언트(다른 CLI 세션, 대시보드 탭, 동일 서버의 AI 에이전트)로 인한 간섭에 영향을 받지 않습니다.
출력 규율
- 파싱을 위해 항상
--json을 전달하세요. 사람/테이블 형식은 안정적인 계약이 아닙니다 — 열 순서와 제목이 릴리스 간에 변경됩니다. - 스트리밍 활동의 경우
jq -c로 파이프하여 한 줄에 하나의 이벤트를 유지하세요. - 사용할 가능성이 있는 모든
--json형태는references/json-shapes.md에 문서화되어 있습니다.jq필터를 작성하기 전에 이를 참조하세요 — 대부분의 형태에는 선택적 필드(기본 행이 null이 아닐 때 표시됨)가 있으며 이를 기준으로 삼아야 합니다.
오류 규율
stderr의 오류에는 항상 code가 포함됩니다:
agent "writer" is not ready: prereqs not acknowledged (HTTP 409, EntryNotReadyError)
agent: acme/writer
cause: prereqs not acknowledged
fix: glyph catalog agent ack-prereqs acme/writer
fix: 라인은 다음에 실행할 명령어 그대로입니다. 전체 code 카탈로그(모든 오류 이름 + 일반 HTTP 상태 + 해결 방법)는 references/error-codes.md에 있습니다. 특히:
EntryNotReadyError는 가장 일반적으로 분기하게 되는 오류입니다 — 에이전트가ack-prereqs가 필요한지,disabled인지,missingDeps가 있는지, 또는blockedDeps(재귀적)가 있는지를 설명하는 구조화된reason을 포함합니다. 이유 표는references/error-codes.md#entrynotreadyerror-reasons에 있습니다.
종료 코드
| 코드 | 의미 | 조치 |
|---|---|---|
| 0 | 성공 | 계속 진행 |
| 1 | 일반 오류 (워크스페이스 누락 포함) | stderr 읽기; 일반적으로 누락된 플래그/환경 변수 |
| 2 | 사용법 오류 (필수 플래그 누락, 제거된 하위 명령) | 호출 수정; 있는 그대로 재시도하지 마십시오 |
| 3 | 서버에 연결할 수 없음 | 사용자에게 glyph start를 요청하거나 --server 확인 |
| 4 | 서버가 4xx/5xx 반환 | stderr에서 code 읽기; references/error-codes.md 참조 |
종료 코드 2는 **"명령 자체가 잘못되었습니다"**를 의미합니다 — 호출을 변경하지 않고 재시도하지 마십시오. 종료 코드 4는 "서버가 이를 거부했습니다"를 의미합니다 — code 필드를 읽으면 다음 조치를 알 수 있습니다.
주의사항
- 작업을 기다리려면
glyph task activity <tid> --follow를 사용하세요 (실시간 SSE). 셸 루프에서task list를 폴링하면 리소스가 낭비되고 실제 이벤트가 지연됩니다. - "지금까지 발생한 상황"의 일회성 스냅샷의 경우
--follow를 생략하세요 —glyph task activity <tid> --json은 한 번의 호출로 현재 활동과totalItems를 반환합니다.--follow는 작업이 종료될 때까지 차단됩니다. - 제거하기 전에 종료하세요. 일반
task rm <tid>는 작업이 종료 상태(succeeded/failed/cancelled)에 있어야 합니다. 아직 실행 중이면 먼저glyph task cancel <tid>를 실행한 다음task rm을 실행하세요.--purge는 작업 디렉토리와 런타임 상태도 제거하려는 경우에만 사용하세요(사후 분석을 위한stderr.log가 손실됩니다).session rm및workspace rm에도 동일한 차이가 적용됩니다. - 항상 출력된
last seq:로--follow를 재개하세요. 깨끗한 종료(event: end또는 스트림 닫힘) 및 스트림 중간 오류 종료 시 CLI는 stderr에last seq: <N>을 출력합니다. 다음--follow호출 시--after <N>을 전달하여 간격이나 중복 없이 재개하세요. Ctrl+C는 예외입니다(stderr가 플러시되지 않음). 대신 마지막 stdout NDJSON 항목에서 시퀀스를 파생하세요(... | tail -1 | jq .seq). 전체 재개 플레이북은references/playbooks.md#monitor-a-long-running-task에 있습니다. - 항상
glyph workspace list --json | jq에서 워크스페이스 ID를 가져오세요. 대시보드 URL 조각은 릴리스 간에 변경되며 유선 계약이 아닙니다. schedule patch는 희소(sparse)합니다 — 전달한 플래그만 와이어로 전송됩니다. 필드를 제거하려면--clear-details/--clear-runtime을 전달하세요(빈--details ""는 생략된 것으로 처리되며 지워지지 않습니다).
참고 자료 (중요한 작업 전 필수 독서)
references/commands.md— 그룹별 하위 명령 참조 (워크스페이스 / 세션 / 작업 / 일정 / 카탈로그 / 워크플로 / 런타임 / 서버 검사). 한 번 훑어보고 조회용으로 유지하세요.references/playbooks.md— 다단계 목표 지향 플레이북 (에이전트 설치 및 확인, 전달 및 대기, 작업 모니터링, 항목 동기화, 정리, 새 워크스페이스 온보딩, 즉석에서 로컬 에이전트 생성).references/json-shapes.md— 일반적인--json페이로드 형태와 구체적인 필드 목록 및 선택 사항 참고 사항.references/error-codes.md— 서버가 방출하는 모든code값과 이에 해당하는glyph수정 명령.