CLI

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

CLI 표면 선택Copy Anchor Link

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에 넣지 않습니다.

앱 --connect 시 운영자 MFA 강제화가 활성 상태이고 계정이 등록 또는 필수 대상이면 브라우저 승인에서 인증 앱의 새 TOTP를 입력하세요. 복구 코드는 로그인 복구용이며 앱 grant 승인을 대신하지 못합니다. 새 CLI 옵션은 필요하지 않으며 기존 서명 grant와 교환 절차는 호환됩니다.

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

서버는 회전 기한 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 설정Copy Anchor Link

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

아래 명시적 역할 허용 예제는 공개 CLI 0.21.0의 --allowed-roles를 보여 줍니다. 이 버전은 예제의 기준판이며 최초·최소 지원 버전이라는 뜻은 아닙니다. 수신자의 역할 허용 설정은 Embedded Admin을 참고하세요.

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에는 포함되지 않습니다.

--actions-file actions.json으로 stable collection action을 최대 20개 설정합니다. 각 항목은 id, label, collection, boolean requiresSelection을 가집니다. 옵션 생략은 기존 actions 보존, 빈 배열은 삭제입니다. 구 strict 서버는 지원하지 않는 action 필드를 거절합니다. 다운로드 정책의 생략 기본값 false는 별도 규칙이므로 actions 보존이 기존 다운로드 설정 보존을 뜻하지는 않습니다. 해당 binding의 iframe에서 파일 다운로드가 필요할 때만 configure에 --allow-downloads를 추가하세요. 기본값은 false이며 옵션 없는 전체 configure는 다운로드를 지원하는 서버에서 기존 true도 false로 바꿉니다. 구 CLI 요청도 같은 의미입니다. 옵션을 생략하면 요청에서 allowDownloads 필드를 생략하고, --allow-downloads는 true, --no-allow-downloads는 false를 명시해 전송합니다. show와 configure readback에 allowDownloads가 포함됩니다. 구 서버의 strict 입력 검증은 이 필드가 있는 configure를 거절하므로 다운로드 옵션을 사용하기 전에 서버부터 업데이트하세요. 파일 암호화·비밀번호 관리는 앱의 책임이며, 이 옵션은 암호화를 강제하거나 이미 받은 파일을 회수하지 않습니다.

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

Admin Panel 필드 표시 설정Copy Anchor Link

write scope 시크릿 키나 tenant-admin의 개인 액세스 토큰으로 활성 워크스페이스의 Admin Panel에 앱이 쓰는 필드만 표시할 수 있습니다. 먼저 설정 가능한 경로를 확인하고, --dry-run으로 변경을 미리 본 뒤 같은 명령을 옵션 없이 실행합니다.

01 field-config list links
01 field-config set links --visible platform,expiresAt --dry-run
01 field-config set links --visible platform,expiresAt

--visible에는 계속 표시할 경로를 넣습니다. 그 컬렉션의 나머지 설정 가능한 경로는 숨겨집니다. 출력은 숨겨질 경로(hide)와 다시 표시될 경로(show)를 보여줍니다. 알 수 없는 경로는 저장 전에 실패하고, 바뀌는 것이 없으면 저장하지 않습니다. 컬렉션 자체의 메뉴 표시 설정은 유지됩니다. 기능이 꺼진 컬렉션도 필드 목록은 보이지만, 기능을 켜기 전에는 저장이 실패합니다. 필드 숨김은 Admin Panel에만 적용되며 저장된 값과 API 읽기·쓰기 권한은 바뀌지 않습니다. 이 명령은 01 agent manifest에 포함되지 않습니다.

로컬 앱 연동 진단Copy Anchor Link

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)입니다.

결제 설정 진단Copy Anchor Link

01 payment diagnose
01 --format json payment diagnose --expected-environment live
01 agent payment diagnose --market <market-uuid> --expected-environment test --pretty

일반 CLI credential resolver의 matching publishable key와 PAT를 사용합니다. PAT가 서버에서 고정한 워크스페이스의 최신 tenant-admin membership과 ecommerce entitlement가 필요합니다. 앱 sk01_, PK-only, customer, 낮은 role은 거부하며 클라이언트의 워크스페이스 지정은 받지 않습니다.

읽기 결과는 managed Toss/PortOne과 custom market 설정 coverage를 구분합니다. 후보 없음/하나/여러 개, 선택된 환경, readiness pin reason, configuration과 저장 secret 존재 boolean, 선택적인 expected environment 비교를 반환합니다. 후보 cardinality를 먼저 확인하고 단일 후보의 provider configuration/secret 조건을 검사합니다. 환경 pin이 없는 legacy 상태는 live readiness 보장이 아닌 관찰 fact입니다. account 목록, MID, client key, secret, ciphertext, customer, money는 반환하지 않습니다. secret 존재는 값이 저장됐다는 뜻이며, 복호화 가능성, key 유효성, provider 권한, 실결제 성공은 provider 환경의 테스트 결제로 확인합니다. managed 설정이 불완전해도 custom 또는 free checkout은 동작할 수 있습니다. 이 명령은 저장된 비밀키의 복호화 검사를 실행하지 않으므로 현재 배포가 읽을 수 없는 비밀키도 존재로 보고합니다. 복호화 가능 여부는 연결 화면이나 워크스페이스 진단에서 확인합니다. PortOne의 설정 완료는 현재 설정으로 명시적으로 요청할 수 있는 profile(Hosted 또는 Standard V2)이 하나 이상 있다는 뜻입니다. 그 profile로 요청하고 제공하는 결제수단을 각각 테스트합니다. 통화 지원은 새 결제 세션 기준을 따릅니다. Toss와 PortOne Standard V2는 KRW, Hosted는 마켓의 ISO 통화로 결제합니다. Console 결제 준비도는 통화를 보지 않으므로 두 결과가 다를 수 있습니다. custom 설정 coverage는 checkout 설정을 따르므로 통화 목록이 없는 custom provider도 설정됨으로 보입니다. custom 결제 세션을 만들기 전에 통화를 추가합니다. 비활성 마켓은 결과와 coverage에서 제외하며, --market으로 지정해도 찾을 수 없는 마켓으로 응답합니다. reason code는 이후 추가될 수 있으므로 모르는 code도 그대로 보존합니다.

Human 기본 출력은 locale에 맞는 text이고 명시적 json, ndjson은 기계용입니다. Agent는 정확히 하나의 JSON 값을 반환하며 manifest version 1의 discovery.payment.diagnose로 발견합니다. 조회가 완료되면 unready 또는 expected environment mismatch fact가 있어도 exit 0입니다. input/auth/query 실패는 기존 namespace error와 exit code를 사용합니다. plan/confirm, idempotency key, provider 호출, attestation, mutation은 수행하지 않습니다.

Agent 계약 discoveryCopy Anchor Link

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합니다.

context는 자격증명과 워크스페이스 연결을 확인하며 배포 준비 상태는 확인하지 않습니다. 초기 설정이 남은 워크스페이스는 이 명령으로 설정이 완료될 수 있으니 상태 변경이 금지된 곳에서는 실행하지 마세요. 비밀값을 명령행 인자로 전달하지 마세요.

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와 GetCopy Anchor Link

모든 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과 ConfirmCopy Anchor Link

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가 아닙니다.

상품 상세와 CommerceCopy Anchor Link

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, RetryCopy Anchor Link

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는 retryable 값에 따라 명령을 자동으로 다시 실행하지 않습니다. 읽기 명령은 오류가 반환되기 전에 SDK 자동 재시도를 이미 거쳤을 수 있습니다. Validation, auth, not-found, plan, monthly quota error는 terminal이고 network/timeout, HTTP 503, transient rate limit, 명시적으로 unavailable한 provider는 retryable일 수 있습니다.

공개 패키지 기준Copy Anchor Link

명령 예제는 공개 @01.software/cli@0.20.1 패키지를 기준으로 합니다. 명시적 역할 허용 예제의 기준판은 CLI 0.21.0입니다.

01 --version으로 설치한 CLI 버전, help로 사용 가능한 명령, 01 agent manifest로 기계가 읽을 수 있는 작업 목록을 확인하세요.

create 0.2.10 / init 0.19.4 / SDK 0.74.0 설정 조합은 빌드 옵션을 참고하고 CLI 버전은 별도로 선택하세요. 실제 워크스페이스 작업에는 해당 자격 증명과 런타임 배포가 필요합니다.

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

다음 액션Copy Anchor Link

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