CLI

운영자 또는 coding agent가 shell 명령을 실행할 수 있을 때 @01.software/cli를 사용합니다. Human CLI 명령은 interactive한 운영자용 표면입니다. 01 agent namespace는 coding agent를 위한 별도 JSON protocol이며 두 표면의 output·exit contract를 섞지 않습니다.

CLI 표면 선택

shell 환경에서 사용하는 package manager로 공개 package를 설치한 뒤 배포된 help를 확인합니다.

npm install --global @01.software/cli
01 --help
01 agent --help

사람 운영자는 01 login, 01 tenant use <name>을 실행할 수 있습니다. 자동화 agent는 신뢰할 수 있는 환경 저장소의 SOFTWARE_PUBLISHABLE_KEY와 SOFTWARE_SECRET_KEY를 우선 사용합니다. 실제 token을 명령 인자, source file, log, chat에 넣지 않습니다.

운영자 MFA 활성화 후 자격 증명 교체

서버는 회전 기한 header를 보내지 않으므로 CLI는 회전 경고를 표시하지 않습니다. 운영자 MFA가 활성화되면 MFA 검증 세션에서 발급되지 않은 super-admin 소유 PAT와 super-admin scope API key는 기존 401 key_invalid로 즉시 사용할 수 없게 됩니다. 01 login을 다시 실행해 운영자 MFA를 완료하고 스크립트·CI·MCP에 저장한 자격 증명을 교체하세요. CLI 업데이트 자체는 MFA 강제화를 활성화하지 않습니다.

Embedded Admin App 설정

Tenant admin은 Human CLI로 현재 tenant의 embedded app binding 하나를 관리합니다. 이 control-plane 작업에는 01 login으로 받은 user PAT가 필요하며 tenant API key(sk01_)는 거부됩니다.

01 tenant use acme
01 embedded-app configure \
  --label "Operations" \
  --origin https://admin.example.com \
  --path /workspace \
  --dry-run
01 embedded-app configure \
  --label "Operations" \
  --origin https://admin.example.com \
  --path /workspace
# Explicit execution-role opt-in (receiver opt-in is also required)
01 embedded-app configure --label Operations --origin https://admin.example.com --allowed-roles tenant-admin tenant-viewer
01 embedded-app show
01 embedded-app disable

--dry-run은 로컬 검증만 하고 쓰지 않습니다. Origin은 하나의 exact HTTPS origin이어야 하고 path에는 query나 fragment가 없는 상대 경로만 허용합니다. 이 명령은 운영자용이며 01 agent의 machine-stable manifest에는 포함되지 않습니다.

--allowed-roles를 생략하면 빈 배열이나 viewer 전용 정책을 포함한 기존 역할 정책을 유지합니다. 새 미설정 정책만 tenant-admin을 기본값으로 사용합니다. 역할을 명시하면 정책을 변경하고 성공 출력은 저장된 역할을 표시합니다. 역할 옵션 없는 로컬 dry-run은 제안하는 PATCH에서 역할 필드를 생략합니다.

로컬 앱 연동 진단

SDK 환경을 구성한 앱 디렉터리에서 redacted 진단을 실행합니다.

01 doctor
01 doctor --app-env-file .env.local
01 doctor --origin https://app.example.com
01 --format json doctor
01 --format ndjson doctor

01 doctor의 기본값은 locale에 맞는 사람용 output이며, 명시적 json과 ndjson format은 기계 소비용입니다. Next.js/CRA에서는 .env, .env.development, .env.local, .env.development.local 순서로, Vite에서는 .env, .env.local, .env.development, .env.development.local 순서로 읽습니다. 그 밖의 앱은 .env와 .env.local만 읽거나 regular file 하나를 --app-env-file로 지정합니다. 앱 publishable/secret 쌍 하나를 검증하고 그 파일에 있는 SDK API target만 해석하며 SDK tenant context를 probe합니다. CLI PAT credential로 fallback하지 않고 credential 값이나 raw response body를 출력하지 않으며 state를 변경하거나 project script를 실행하지 않습니다. --origin은 Authorization 또는 secret을 보내지 않는 CORS OPTIONS 진단입니다. origin은 절대 http(s) URL이어야 합니다. 403은 ACAO가 있어도 거부이며, 성공 응답은 ACAO가 정확히 맞아야 합니다. 404, 408, 429, 5xx, network 실패는 CORS 결론을 내리지 않는 상태입니다.

01 agent doctor는 정확히 하나의 JSON 값을 반환합니다. 완료된 진단은 payload가 blocked 또는 attention이어도 Agent success(0)로 끝나며, 명시적 app-env-file이 또는 origin이 유효하지 않으면 Agent INVALID_INPUT(exit 2)입니다.

Agent 계약 discovery

help text를 parsing하지 말고 manifest로 모든 Agent CLI 연동을 시작합니다.

01 agent manifest --pretty
01 agent context --counts --pretty
01 agent schema articles --pretty

version 1 manifest는 현재 server-auth collection과 지원 operation을 나열합니다. context는 활성 tenant, feature, 활성 collection, field configuration을 반환합니다. schema는 tenant-effective field contract를 반환합니다. Schema의 writable metadata는 advisory이며 서버 access control과 manifest의 검토된 plan operation이 authoritative합니다.

customers와 products의 schema에는 optional collection.customFields와 storagePath: "customData"가 포함될 수 있습니다. 각 active definition은 machine key와 type, optional required: true, select option의 저장값만 포함합니다. 표시 label, help text, 내부 id, tenant metadata는 제외됩니다. 이 구조 discovery는 저장된 customData 값의 접근 권한이나 새로운 write operation을 부여하지 않습니다.

Query와 Get

모든 manifest collection은 query와 get을 지원합니다. filter, pagination, sort, field selection으로 agent context를 작게 유지합니다.

01 agent query articles \
  --where '{"status":{"equals":"published"}}' \
  --limit 10 \
  --sort=-updatedAt \
  --select=id,title,updatedAt

01 agent get articles art_123 --select=id,title,updatedAt --pretty

query는 paginated Payload shape를, get은 bare document 하나를 반환합니다. --limit와 --page에는 양의 10진 정수만 사용할 수 있습니다.

콘텐츠 변경 Plan과 Confirm

Agent write는 의도적으로 두 단계입니다. plan은 input을 검증하고 remote data를 변경하지 않은 채 만료되는 local plan을 저장합니다. JSON을 검토한 뒤 반환된 confirmCommand의 정확한 token과 hash로 실행합니다.

printf '%s\n' '{"title":"Release notes","status":"draft"}' | \
  01 agent plan create articles --data-stdin --pretty

01 agent confirm <planToken> --hash <planHash> --pretty

Mutation payload는 --data-stdin 또는 --data-file로만 받습니다. 현재 manifest는 articles와 article categories/tags, links와 link categories/tags, 그리고 canvases, canvas-categories, canvas-tags의 create/update/delete plan을 제공합니다. documents, document-categories, document-types는 create/update만 제공하며 delete는 제공하지 않습니다. canvas-node-types와 canvas-edge-types catalog는 Agent CLI에서 계속 read-only입니다. Schema field로 write 지원을 추론하지 않습니다.

Plan은 기본 15분 후 만료되고 현재 auth/API context에 묶이며 update/delete 대상이 stale이면 거부합니다. Remote mutation이 실패하면 plan은 pending으로 돌아가므로 유효 기간 안에 같은 token과 hash로 confirm을 재시도할 수 있습니다. Mutation이 성공한 뒤 claimed 또는 consumed 상태인 plan은 replay하면 안 됩니다. Human CLI --dry-run은 별도 운영자 workflow이며 Agent plan contract가 아닙니다.

상품 상세와 Commerce

Agent namespace는 generic collection read에 더해 shaped product read를 제공합니다.

01 agent product detail \
  --slug canvas-bag \
  --market kr \
  --locale en \
  --fallback-locale ko \
  --pretty

--slug와 --id 중 정확히 하나를 사용합니다. 판매 불가능한 상품은 {"found":false,"reason":"not_published"} 같은 성공 discriminated result를 반환합니다.

Agent namespace는 현재 commerce mutation command를 제공하지 않습니다. 운영자용 명령이 맞으면 01 order --help, 01 cart --help, 01 checkout --help, 01 payment-session --help와 관련 group에 있는 기존 Human CLI domain command를 사용하고, 애플리케이션 또는 자동화 commerce mutation에는 server SDK를 사용합니다. Human CLI text/output 또는 exit code를 Agent JSON contract로 취급하지 않습니다.

Cart capability 작업, Checkout 생성, PaymentSession 생성/취소/확인의 민감한 JSON은 --data-stdin 또는 --data-file 중 하나로만 입력합니다. 대화형 stdin은 거부하고 입력 크기는 1 MiB로 제한합니다. 성공한 --dry-run도 action과 유효성만 출력하며 payload 값은 되돌려주지 않습니다. Cart/Checkout capability, 고객 snapshot, idempotency key, provider 승인 정보가 shell history, process 목록, 로그에 남는 것을 방지하기 위한 규칙입니다. 입력 파일은 접근 권한을 제한하고 사용 후 삭제하세요. 01 cart create는 예외로, request에 capability가 없으므로 입력 없이 canonical 기본값을 사용할 수 있습니다. 선택적인 market 또는 attributes를 지정할 때만 민감 입력 source를 사용합니다.

Output, Error, Retry

Agent success와 normal error는 각각 stdout에 정확히 하나의 JSON 값을 출력합니다. --pretty는 success JSON을 2-space indent로 만듭니다. --output-file <path>는 전체 success result를 secure file에 쓰고 outputFile과 bytes가 있는 compact stdout receipt를 반환합니다.

01 agent query articles --limit 100 --output-file ./articles.json

POSIX에서 result file은 mode 0600을 사용하며 symlink, directory, hard link가 여러 개인 file 같은 unsafe target은 거부됩니다.

Normal error envelope에는 error.code, error.message, error.retryable이 있습니다. retryable이 true일 때만 재시도하고 retryAfter가 있으면 지키며 operation idempotency를 유지합니다. CLI는 caller 대신 자동 재시도하지 않습니다. Validation, auth, not-found, plan, monthly quota error는 terminal이고 network/timeout, HTTP 503, transient rate limit, 명시적으로 unavailable한 provider는 retryable일 수 있습니다.

공개 패키지 기준

명령 예제는 공개 @01.software/cli@0.20.1 패키지를 대상으로 합니다. 설치한 패키지의 01 --version, help, 01 agent manifest를 확인하고 현재 저장소나 승인된 설계만으로 설치된 verb를 추측하지 마세요. create 0.2.5 / init 0.14.3 / SDK 0.65.x 설정 조합은 빌드 옵션에 있으며 CLI 버전을 선택하지 않습니다. 실제 tenant operation에는 해당 credential과 runtime 배포가 필요합니다.

CLI 설정 후 browser/server 세션 protocol은 Embedded Admin을 따릅니다.

다음 액션

• 자격 증명 경계가 필요하면 인증과 키를 엽니다.
• 타입 기반 앱 코드 또는 commerce mutation이 필요하면 SDK를 엽니다.
• 직접 HTTP escape hatch가 필요하면 API를 엽니다.
• hosted·shell 없는 discovery가 필요하면 MCP를 엽니다.