CLI 참조

Schift CLI(명령줄 인터페이스)는 파일 업로드, 버킷(bucket) 검색, 임베딩(embeddings) 벤치마크(benchmark) 실행, 사용량(usage) 조회 등 워크스페이스(workspace) 작업을 위한 터미널 중심(terminal-first) 인터페이스를 제공합니다.

schift 실행 파일 이름을 공유하는 두 가지 패키지(Package)가 있습니다.

패키지(Package)	지원 형태(Surface)	용도(Use for)
schift-cli (Python)	표준, 지속 유지보수	버킷, 업로드, 검색, 카탈로그, 임베딩, 작업, 사용량, 벤치마크, 마이그레이션
@schift-io/cli (npm)	호환성 전용	레거시 배포, 제공자, 에이전트, AWP, 메모리 워크플로우

참고: 새로운 터미널(terminal) 워크플로우는 Python schift-cli를 사용해야 합니다. npm CLI는 upload, search, catalog, migrate 같은 표준 데이터 명령(canonical data commands)을 의도적으로 Python CLI로 리디렉션하고 설치 안내를 함께 제공합니다.

설치

Python CLI(표준)

python3 -m pip install schift-cli

저장소에서 로컬 개발용으로 설치하려면:

cd clients/sdk/cli
python3 -m pip install -e '.[dev]'

이 패키지는 pyproject.toml 콘솔 진입점(console entry point)을 통해 schift 실행 파일을 설치합니다.

npm CLI(호환성)

npm install -g @schift-io/cli

이 CLI는 schift deploy, schift providers, schift agent와 같은 이전 TypeScript 전용 명령 표면(TypeScript-only command surface)이 필요할 때만 사용하세요.

인증

대화형으로 또는 환경 변수(environment variables)를 통해 인증합니다.

# 대화형 로그인 — API 키를 ~/.schift/config.json에 저장합니다
schift auth login

# 현재 인증 출처 확인
schift auth status

# 저장된 키 삭제
schift auth logout

CLI는 다음 순서로 인증 정보(credentials)를 해석합니다.

1. SCHIFT_API_KEY 환경 변수(environment variable)
2. ~/.schift/config.json

둘 다 있으면 환경 변수가 우선합니다. 설정 파일은 0600 권한(permissions)으로 기록됩니다.

설정

API 기본 URL은 SCHIFT_API_URL에서 해석됩니다. 이 변수가 없으면 CLI는 프로덕션 원점(production origin)을 가정하지 않으므로, 로컬, 스테이징(staging), 호스팅된 워크스페이스(hosted workspaces)에 대해 명시적으로 설정하세요.

export SCHIFT_API_KEY=sch_your_key_here
export SCHIFT_API_URL=http://localhost:8080/v1

명령 그룹

표준 Python 명령

명령(Command)	용도(Purpose)
schift auth ...	로컬 인증 상태 관리
schift catalog ...	지원되는 임베딩 모델 조회
schift embed ...	텍스트에서 임베딩 생성
schift bench ...	두 모델 간 마이그레이션 품질 평가
schift migrate ...	투영(projection)을 적합시키고 quote/start/status 데이터베이스 마이그레이션 실행
schift db ...	버킷 생성, 목록 조회, 상세 조회
schift upload ...	버킷에 파일 업로드
schift jobs ...	수집 작업(ingest jobs) 조회, 재처리, 취소
schift search ...	버킷 검색 실행
schift query ...	search의 호환성 별칭
schift usage ...	집계된 사용량과 과금 요약 표시

호환성 npm 명령

명령(Command)	용도(Purpose)
schift auth login|logout|status	인증하거나 저장된 인증 정보(credentials) 삭제
schift deploy	레거시 배포 호환성(데이터 업로드, 버킷 생성)
schift agent call	배포된 에이전트 질의 엔드포인트(query endpoint) 호출
schift awp publish-pack	자사 AWP YAML 팩(pack) 게시
schift providers set	조직 수준(org-level) LLM 제공자(provider) 접근 설정
schift remember, ask, ingest	레거시 메모리 워크플로우

예제

버킷 업로드 및 검색

schift auth login
schift upload ./handbook.pdf --bucket company-docs
schift jobs list --bucket company-docs
schift search "revenue report" --bucket company-docs --top-k 5

모델 조회 및 텍스트 임베딩

schift catalog list
schift catalog get openai/text-embedding-3-large
schift embed "quarterly revenue report" --model openai/text-embedding-3-large

배치 임베딩

schift embed batch \
  --file ./texts.jsonl \
  --model google/gemini-embedding-004 \
  --output ./embeddings.jsonl

입력 형식:

{"text":"First document"}
{"text":"Second document"}

출력 형식:

{"text":"First document","embedding":[0.123,0.456]}
{"text":"Second document","embedding":[0.789,0.012]}

마이그레이션 벤치마크

schift bench \
  --source openai/text-embedding-3-large \
  --target google/gemini-embedding-004 \
  --bucket-source ./bucket-source.npy \
  --bucket-target ./bucket-target.npy \
  --query-source ./query-source.npy \
  --query-target ./query-target.npy \
  --bucket-document-id doc_1 \
  --bucket-document-id doc_2 \
  --top-k 10

실제 마이그레이션 전에 bench를 안전 관문(safety gate)으로 사용하세요. 낮은 재현율(recall)은 롤아웃(rollout)을 차단해야 합니다.

투영 적합 및 데이터베이스 마이그레이션

schift migrate fit \
  --source openai/text-embedding-3-large \
  --target google/gemini-embedding-004 \
  --source-embeddings ./source.npy \
  --target-embeddings ./target.npy \
  --project-name docs-migration

schift migrate quote --from 'pgvector://user:password@localhost:5432/app?table=docs'

schift migrate start \
  --from 'pgvector://user:password@localhost:5432/app?table=docs' \
  --to schift://bucket_abc123

참고: migrate run은 공개 API가 더 이상 /migrate/run을 노출하지 않으므로 폐기되었습니다. 대신 migrate quote, migrate start, migrate status를 사용하세요.

환경 변수(Environment variables)

변수(Variable)	용도(Purpose)
SCHIFT_API_KEY	인증용 API 키(API key). ~/.schift/config.json보다 우선합니다.
SCHIFT_API_URL	Schift API의 기본 URL(Base URL). 예: http://localhost:8080/v1.

오류 처리 및 종료 동작

• 인증 실패(Authentication failures)는 schift auth login을 실행하라는 직접적인 안내 메시지를 출력합니다.
• 연결 실패(Connection failures)는 해석된 API URL을 언급하고 SCHIFT_API_URL을 확인하라고 안내합니다.
• API 오류(API errors)는 0이 아닌 코드로 종료하며, 사용 가능한 경우 서버가 제공한 상세 텍스트를 표시합니다.
• 빈 결과 집합(Empty result sets)은 정상 출력으로 처리되며, 충돌이 아닙니다.

참고

• SDK Reference
• Embeddings API
• Jobs API
• Buckets