@ssobig/writer-cli

SSOBIG WRITER의 공식 Agent CLI다. Google 계정으로 로그인한 뒤 본인이 소유하거나 공유받은 Writer 작품을 서버 권한 범위 안에서 읽고, 검토된 plan만 적용한다.

현재 지원 환경은 macOS, Windows 10/11 또는 Linux와 Node.js 22.13.0 이상이다. CLI는 일반 Writer 회원의 소유자·공동 편집자·뷰어 권한을 그대로 사용하며, server RLS와 focused RPC를 우회하지 않는다.

설치

npm install --global @ssobig/writer-cli@latest
ssobig-writer doctor
ssobig-writer skills install --target <내-workspace>
ssobig-writer auth login
ssobig-writer auth whoami
ssobig-writer project list

CLI는 stdout에 JSON 문서 하나를 출력한다. 원고 변경은 plan -> 사람 검토 -> apply -> authoritative read-back 절차만 사용하며, 범용 SQL이나 직접 table update를 제공하지 않는다.

등록된 이미지·JSON 원본은 로그인 사용자의 비공개 Storage 읽기 권한으로 내려받는다. Writer 데이터는 변경하지 않고 기존 로컬 파일도 덮어쓰지 않는다. --out 확장자는 asset list의 MIME type에 맞춘다.

ssobig-writer asset list --project <slug>
ssobig-writer asset download --project <slug> --asset-id poster --out .ssobig-writer/poster.webp

다운로드 결과에는 localPath, size, contentHash가 포함된다. 원본 크기·hash·파일 형식을 확인하고, 없는 에셋·tombstone·권한 거절·손상된 다운로드는 실패로 보고한다.

작품 구성 화면의 등록된 선택 Component 추가·사용 여부와 선택 속성도 같은 절차로 변경할 수 있다.

ssobig-writer component plan-add --project <slug> --template ssobig.timeline --out .ssobig-writer/component-add.plan.json
ssobig-writer apply .ssobig-writer/component-add.plan.json --receipt .ssobig-writer/component-add.receipt.json

ssobig-writer component plan-set-active --project <slug> --instance timeline --active false --out .ssobig-writer/component-archive.plan.json
ssobig-writer component plan-set-field --project <slug> --instance clues --field image --enabled false --out .ssobig-writer/field.plan.json

patch·spec·plan·receipt는 기밀 원고를 포함할 수 있으므로 ignored .ssobig-writer/ 또는 private 경로에 보관하고 커밋하지 않는다.

plan에서 대상, 보존할 data, 생성·제거될 View·binding 또는 enabledOptionalFields 변경을 먼저 검토해야 한다. 사용 안 함은 data를 삭제하지 않고 보관하며, 필수·내부·미등록 Component와 필수·미등록 속성 및 임의 구성 변경은 허용하지 않는다.

업데이트와 제거

ssobig-writer version --check
npm install --global @ssobig/writer-cli@latest
ssobig-writer skills status --target <내-workspace>
# status가 missing이면 install, update-available이면 update, current이면 추가 작업 없음
ssobig-writer skills update --target <내-workspace>

ssobig-writer auth logout
ssobig-writer agent purge
ssobig-writer skills remove --target <내-workspace> --managed-only --dry-run
ssobig-writer skills remove --target <내-workspace> --managed-only
npm uninstall --global @ssobig/writer-cli

0.2.0부터 npm latest보다 낮은 CLI의 서버 접속 명령은 실행 전에 E_CLI_UPDATE_REQUIRED로 중단된다. help, targeted command-schema, version --check, doctor, skills *, logout과 daemon 정리 명령은 업데이트 전에도 사용할 수 있다. 0.1.0 사용자는 위 npm 설치 명령을 다시 실행해 0.2.0 이상으로 전환해야 한다. registry가 일시적으로 응답하지 않으면 새 작업을 차단하지 않지만, 로컬 cache가 이미 더 높은 버전을 확인했다면 계속 업데이트를 요구한다.

CLI를 업데이트한 뒤에는 각 작업공간에서 skills status를 확인하고, missing이면 skills install, update-available이면 skills update를 실행한다. 그다음 새 Codex 또는 Claude 작업을 열어 갱신된 프로젝트 로컬 스킬을 다시 탐색한다. CLI 설치는 작업공간을 자동 변경하지 않는다. CLI 배포는 npm만 지원하며 ZIP이나 운영체제별 installer는 제공하지 않는다.

doctor는 설치·최신 버전·credential session 존재·Auth health·실행 backend 버전을 읽기 전용으로 진단하고 token, 이메일, 원고 값을 출력하지 않는다. macOS 세션은 Keychain에 저장되고 private Unix daemon을 사용한다. Windows 세션은 현재 Windows 사용자만 해독할 수 있도록 DPAPI CurrentUser로 보호되며 CLI는 background daemon 대신 in-process backend를 자동 사용한다. 따라서 Windows에서는 agent start와 agent stop이 지원되지 않는다. Linux 세션은 Secret Service(secret-tool, D-Bus, 잠금 해제된 keyring 필요)에 저장되고 private Unix daemon을 사용한다.

OS 보호 저장소를 쓸 수 없으면 CLI는 자동 대체 없이 중단한다. 위험을 이해한 경우에만 Linux·macOS에서 SSOBIG_WRITER_CREDENTIAL_STORE=file을 직접 설정해 권한 제한 평문 파일 저장소를 쓸 수 있고, SSOBIG_WRITER_CREDENTIAL_DIR=<절대 경로>로 재시작 뒤에도 유지되는 volume을 지정할 수 있다. 이 저장소는 암호화가 아니며 0700 directory·0600 파일 권한만으로 보호되므로 같은 OS 사용자 프로세스, root, snapshot·backup 접근자가 세션을 읽을 수 있다. 재시작 뒤에는 같은 환경변수로 ssobig-writer auth whoami를 다시 실행해 유지 여부를 확인한다.

브라우저와 CLI가 다른 컴퓨터에 있으면 원격 2단계 로그인을 사용한다.

ssobig-writer auth login --no-browser
# 출력된 authorizationUrl을 아무 브라우저에서 열어 로그인하고,
# 열리지 않는 http://127.0.0.1:<port>/auth/callback?... 주소창 전체 URL을 복사한다.
ssobig-writer auth login --callback-url "<복사한 전체 URL>"

요청은 10분 동안 한 번만 사용할 수 있다.

상세 설치, 업데이트, 삭제 방법은 SSOBIG WRITER 운영 가이드에서 확인한다.

작업별 안내

설치된 ssobig-writer-cli 스킬은 필요한 참조만 선택한다. 패키지 안에서도 조회와 검색, 변경 계획, 추리 보드와 spec, 오류 복구를 읽을 수 있다.