CLI Reference

The Schift CLI provides a terminal-first interface for workspace operations such as uploading files, searching buckets, running embedding benchmarks, and inspecting usage.

There are two packages that share the schift executable name:

Package	Surface	Use for
`schift-cli` (Python)	Canonical, maintained	Buckets, upload, search, catalog, embeddings, jobs, usage, benchmarks, migrations
`@schift-io/cli` (npm)	Compatibility-only	Legacy deploy, provider, agent, AWP, and memory workflows

Note: New terminal workflows should use the Python schift-cli. The npm CLI intentionally redirects canonical data commands such as upload, search, catalog, and migrate to the Python CLI with an install hint.

Installation

Python CLI (canonical)

python3 -m pip install schift-cli

For local development from the repository:

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

The package installs a schift executable through the pyproject.toml console entry point.

npm CLI (compatibility)

npm install -g @schift-io/cli

Use this only when you need the older TypeScript-only command surface such as schift deploy, schift providers, or schift agent.

Authentication

Authenticate interactively or through environment variables.

# Interactive login — stores the API key in ~/.schift/config.json
schift auth login

# Inspect the current authentication source
schift auth status

# Remove the stored key
schift auth logout

The CLI resolves credentials in this order:

SCHIFT_API_KEY environment variable
~/.schift/config.json

If both are present, the environment variable wins. The config file is written with 0600 permissions.

Configuration

The API base URL is resolved from SCHIFT_API_URL. The CLI does not assume a production origin when this variable is missing, so set it explicitly for local, staging, or hosted workspaces.

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

Command groups

Canonical Python commands

Command	Purpose
`schift auth ...`	Manage local authentication state
`schift catalog ...`	Browse supported embedding models
`schift embed ...`	Generate embeddings from text
`schift bench ...`	Evaluate migration quality between two models
`schift migrate ...`	Fit projections and run quote/start/status database migrations
`schift db ...`	Create, list, and inspect buckets
`schift upload ...`	Upload files into a bucket
`schift jobs ...`	Inspect, reprocess, and cancel ingest jobs
`schift search ...`	Run bucket search
`schift query ...`	Compatibility alias for `search`
`schift usage ...`	Show aggregated usage and billing summary

Compatibility npm commands

Command	Purpose
`schift auth login\|logout\|status`	Authenticate or clear stored credentials
`schift deploy`	Legacy deploy compatibility (upload data, create bucket)
`schift agent call`	Call a deployed agent query endpoint
`schift awp publish-pack`	Publish first-party AWP YAML pack(s)
`schift providers set`	Configure org-level LLM provider access
`schift remember`, `ask`, `ingest`	Legacy memory workflows

Examples

Upload and search a bucket

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

Browse models and embed text

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

Batch embeddings

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

Input format:

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

Output format:

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

Benchmark a migration

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

Use bench as a safety gate before a live migration. Low recall should block rollout.

Fit a projection and migrate a database

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

Note: migrate run is retired because the public API no longer exposes /migrate/run. Use migrate quote, migrate start, and migrate status instead.

Environment variables

Variable	Purpose
`SCHIFT_API_KEY`	API key for authentication. Takes precedence over `~/.schift/config.json`.
`SCHIFT_API_URL`	Base URL for the Schift API, for example `http://localhost:8080/v1`.

Error handling and exit behavior

Authentication failures print a direct action message telling you to run schift auth login.
Connection failures mention the resolved API URL and suggest checking SCHIFT_API_URL.
API errors exit non-zero and surface server-provided detail text when available.
Empty result sets are handled as normal output, not crashes.