Communitygithub.com

glyph CLI 스킬

Glyph는 오늘날 인텔리전스가 취하는 형태를 구성하고, 내일它将 사용할 언어를 발견하기 위한 워크벤치입니다.

glyph CLI 스킬란 무엇인가요?

이 스킬은 AI 에이전트가 Glyph 서버의 CLI를 완전히 제어할 수 있도록 설계된 공식 CLI 스킬입니다. `glyph` 명령어의 전체 표면을 매핑하여, `--help`만으로는 알 수 없는 워크스페이스 스코핑 규율과 오류 처리 규율을 제공합니다. 특히 `GLYPH_WORKSPACE` 환경 변수를 기반으로 한 워크스페이스 선택 규칙을 통해 여러 클라이언트 간의 명령 충돌을 방지하며, 종료 코드(exit code) 기반의 체계적인 오류 분기 처리를 지원합니다. 지원하는 주요 기능 그룹으로는 workspace, session, task, schedule, catalog, workflow, runtime 관리와 서버 상태 확인(health, config, status)이 있습니다. 모든 명령은 `--json` 플래그를 지원하여 파싱 가능한 출력을 제공하며, 오류 발생 시 `code` 필드와 `fix:` 라인을 통해 구체적인 문제 원인과 해결 명령어를 제시하여 AI 에이전트가 자동으로 복구 절차를 수행할 수 있도록 돕습니다. 이 스킬은 Glyph 서버와의 상호작용을 완전 자동화하려는 AI 에이전트에게 필수적인 참조 문서입니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add glyphs-ai/glyph

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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
scheduleCron 트리거 작업 실행기 (만들기/목록/수정/활성화/비활성화/실행/미리보기/작업 목록)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 수정 명령.

관련 스킬