CLI Reference

CLI Reference

This page documents the FrameShift 0.10.0 command surface. Run frameshift --version to check the binary on your path and frameshift <command> --help for the complete option set accepted by that binary.

Installation

Build the CLI from this workspace:

cargo build --release -p frameshift-cli

The binary is named frameshift.

Command index

Command	Purpose
account	Log in, inspect, or end an account session
install	Install a persona pack into the central store
activate	Activate an installed persona for the current project
uninstall	Remove an installed persona from the current project
list	List personas installed for the current project
sync	Reconcile the central store with the project lockfile
gc	Remove unreferenced central-cache entries
project-id	Print the current project's stable ID
rule	Add or remove a typed rule in persona source
skill	Add or remove a typed skill in persona source
diff	Compare two persona sources semantically
render	Render persona source for an agent target
migrate	Move legacy project files into the central store
grow	Append, inspect, or summarize local growth
verify	Run persona conformance checks
publish	Package a persona locally or publish it to a registry
register	Register this machine's author key under a registry handle
keys	Manage local and account-enrolled publisher keys
search	Search the registry pack catalog
select	Rank personas without activating one
use	Activate a persona and print its rendered output
automate	Manage per-project Automate policy
prefs	Inspect or adjust selection preference biases
feedback	Record a selection override for preference learning
config	Get or set current-project configuration
vault	Manage encrypted template-token values

Persona lifecycle

frameshift account <ACTION>

Use login, status, or logout to manage the current account session.

frameshift install [OPTIONS] <SPEC>

Install a persona by name@version. Use --from-path <PATH> to install from a local pack directory instead of the registry.

frameshift install cryptographic@0.1.0 --from-path ./personas/cryptographic

frameshift activate <PERSONA>

Activate an installed persona for the current project.

frameshift uninstall <PERSONA>

Remove an installed persona from the current project.

frameshift list

List the personas installed for the current project.

frameshift sync

Reconcile installed content with the project lockfile and report any materialization failures.

frameshift gc

Remove central-cache entries that no project lockfile references.

frameshift use [OPTIONS] <NAME>

Activate a persona and print its rendered content. --from <DIR> installs <DIR>/<NAME> first if the persona is not already installed. --target selects claude, codex, gemini, or generic; the default is generic.

frameshift use cryptographic --from ./personas --target codex

frameshift project-id

Print the SHA-256 project ID derived from the canonical project-root path.

Discovery and Automate

frameshift search [QUERY] [--tag <TAG>] [--limit <COUNT>]

Search the registry catalog by text and optional tag.

frameshift select [--task <TEXT>] [--library <DIR>] [--format table|json]

Rank personas without changing active state. Table output is the default. JSON output includes the context snapshot, component scores, matches, and rationale.

frameshift select --task "debug a rust compilation error"
frameshift select --task "debug a rust compilation error" --format json

frameshift automate <ACTION>

Actions are on, off, status, lock, and unlock. on accepts an optional sensitivity from 0.0 to 1.0.

Enabling Automate stores project policy. It does not independently select or activate a persona. A connected host or the FrameShift daemon must run the selection and activation loop. lock pins the current persona; unlock allows the host loop to switch again.

frameshift prefs <ACTION>

Actions are show, bump, decay, and reset. The mutation actions operate on per-persona preference biases used by selection.

frameshift feedback --chosen <PERSONA> [OPTIONS]

Record a manual selection override. Optional fields include the automatic pick, task, inferred intent, and reason.

frameshift feedback --auto-pick frontend --chosen rust --intent debugging

Source authoring and growth

frameshift rule add|remove

Modify typed rules in a persona's rules.toml.

frameshift skill add|remove

Modify typed skills in a persona's skills.toml.

frameshift diff [--json] <PERSONA_A> <PERSONA_B>

Compare two persona sources. The report covers rule, skill, voice, and anchor changes; --json emits machine-readable output.

frameshift render [--target <TARGET>] <PERSONA>

Render source for claude, codex, gemini, or generic.

frameshift migrate

Move supported legacy project files into the central FrameShift store.

frameshift grow <ACTION>

append records a local observation, log reads growth history, and summary produces the deduplicated summary.

frameshift grow append --persona rust --text "Prefer a newtype when trait coherence blocks a direct implementation."

Verification, identity, and publishing

frameshift verify [OPTIONS]

Run conformance checks. Exactly one of --persona <PERSONA> or --bundle <DIR> is required. Optional controls include --canned-response, --threshold, --runner mock|cli, and --model. The cli runner requires --persona.

frameshift verify --persona rust --runner mock

frameshift register --server <URL> --handle <HANDLE> [--display-name <NAME>]

Register this machine's author key under a registry handle.

frameshift keys <ACTION>

Manage publisher keys. Available actions are init, list, create, label, select, enroll, remote-list, rotate, revoke, remote-revoke, recover, export, and import. Use the action-specific --help before a mutation.

frameshift publish --persona <PERSONA> [OPTIONS]

Package a persona into --out <DIR> or publish it through --server <URL> under --handle <HANDLE>.

Project configuration and vault

frameshift config get|set

Read or update a key in the current project's central config.toml.

frameshift vault <ACTION>

Actions are init, set, get, rm, and list. The vault holds encrypted values used to resolve persona template tokens.