CLI reference

Commands print JSON when stdout is a pipe and text at a terminal; errors go to stderr with a nonzero exit code. Global options: --dry-run, -o, --output <json|text|auto>, --root <path>, --home <path>, and --global to target the shared global configuration at ~/.preflight/global. preflight <command> --help is authoritative. New here? Follow the Quickstart.

Output format

Option	Result
`-o json` (or `--json`)	the JSON contract. Scripts can rely on it. Errors are JSON on stderr: `{"error": "..."}`
`-o text` (or `--text`)	a table or `key: value` rendering for people. Errors are one line on stderr: `error: ...`
`-o auto` (default)	`text` at a terminal, `json` when stdout is a pipe or a file

doctor and instructions use their own grouped text. status, list, detect, search, source list, profiles list, loadouts list and usage have a dedicated text form. Every other command prints its JSON as aligned key: value lines and tables. Output sent to a pipe is the same JSON as in earlier versions.

Status

preflight status shows one line per harness (Claude Code, Codex, Cursor): installed or not, config folders, active profile, and the number of skills, MCP servers, subagents, plugins, hooks and instruction files, as global/project. It also counts doctor findings (errors, warnings, info) for each harness. It reads configuration files only. It does not read transcripts, start MCP servers or run hooks. preflight with no arguments at a terminal prints the help and suggests this command.

Setup and state

Command	Purpose
`status`	one line per harness: installed, profile, resource counts, doctor findings
`init`	create a project configuration
`list`	list desired resources
`validate <file>`	validate a desired-state configuration
`profiles`	create, switch and diff profiles
`sync`	reconcile desired state to harness files
`audit`	show the append-only change history

Inspect and adopt

Command	Purpose
`detect`	read installed harness resources
`unmanaged`	what a harness holds that the profile does not manage
`adopt <id>`	manage a detected resource where it already lives
`inspect <id>`, `inspect-json <json>`	content, permissions, configuration, provenance
`doctor [--connect] [--days n] [--processes] [--measure] [--no-transcripts]`	findings by severity with fix and token cost; see Doctor
`instructions lint [file]` / `instructions draft [--scope] [--agent] [--write]`	lint or draft CLAUDE.md / AGENTS.md; see Doctor
`verify <id> [--connect]`	static check, or initialise the MCP server and list tools

Change resources

Command	Purpose
`create <file>`, `create-json <json>`	add a resource
`update <id> <file>`, `update-json`	patch a resource
`delete <id>`	remove it and its managed wiring
`fork <id> <new-id>`	duplicate under a new identity
`move <id> <scope>`	switch between global and project scope
`rollback`, `recover`	reverse the latest transaction, or restore an interrupted one

Find and install

Command	Purpose
`source add\|list\|show\|update\|remove`	content sources the catalogue and loadouts come from; see Sources
`search [query]`	catalogue search; `--source`, `--type`, `--online`, `--github <owner/repo>`, `--catalog <dir>` choose and add sources
`catalog-inspect <id>`, `catalog-add <id>`	inspect, then add an item from a source
`catalog build <dir>`	write a content repository's `catalog/index.json`; `--check` in CI
`inspect-file <file>`	validate a catalogue resource file
`install <owner/repo>`	scan any repository and install what it holds; see Install from a repository
`install <id>`	print the package-manager plan; `--execute` runs it

Install from a repository

preflight install reads any GitHub repository, or a local folder. The repository needs no catalog/index.json.

preflight install anthropics/skills                      # preview: what it holds, where it would go
preflight install anthropics/skills --select pdf,docx    # preview two resources
preflight install anthropics/skills --select pdf --apply # write them
preflight install github:acme/tools@v2/skills/pdf        # one folder at a tag
preflight install https://github.com/acme/tools --all --harness claude-code,codex --apply
preflight install ./my-repo --all --scope global --apply

Argument or option	Effect
`owner/repo`, `owner/repo@ref`, `github:owner/repo[@ref][/folder]`	A GitHub repository. Without a ref, Preflight reads the default branch. The ref is resolved to a commit, and that commit's tarball is cached in `~/.preflight/sources/_install/`. A ref with a slash is not accepted; use a tag or a commit.
`https://github.com/owner/repo[/tree/<ref>/<folder>]`	The same, as a URL.
`./folder`, `~/folder`, `/abs/folder`	A local folder, read in place.
(no option)	Preview only. The JSON lists the resources found by type, the agents detected on this machine, the agents that can take each resource and the reason for each that cannot, and the file changes to install all of them. Nothing is written.
`--select <id,...>` or `--all`	Choose resources by id (`skill:pdf`) or name.
`--harness claude-code,codex,cursor`	The agents to install into. The default is every agent detected here.
`--scope global\|project`	The default is project, or global in the global workspace.
`--apply`	Write the files. `--apply` needs `--select` or `--all`. `--dry-run` overrides it.

Preflight finds these files. The agent-kit layout of Sources is also read.

In the repository	Becomes
every `SKILL.md`, with the other text files in its folder	`skill`
`*.md` in an `agents/` folder	`subagent`
`*.md` in a `commands/` folder	`command`
`.mcp.json` or `mcp.json` (`mcpServers`, or a bare map of servers)	`mcp`
`.claude-plugin/marketplace.json`	`plugin`

Each agent receives the resource in its own format, through the same adapters as every other resource: Claude Code JSON, Codex config.toml tables, Cursor mcp.json. When an agent has no equivalent, the preview names the resource, the agent and the reason. Examples: Codex has no subagents or commands, and no SSE MCP servers; plugins, hooks and the status line are Claude Code only. These resources are never installed:

An MCP server that runs a file from the repository (./server.js), because Preflight copies the configuration, not the server.
A configuration that holds a literal secret.
A skill folder with a binary file, or more than 200 files or 2 MB.

A skill inside a plugin folder goes to Codex and Cursor one by one. For Claude Code it comes with the plugin when you select the plugin too.

Each installed resource records its origin: the repository, the commit and the file's path. preflight list shows it, doctor reports a changed file as drift, and preflight delete <id> removes the resource and its files. To update a resource, install it again from the same repository; Preflight replaces it. Preflight refuses to replace a resource with the same id from another place.

In the desktop app, Discover > Discover resources > From GitHub does the same: enter the repository, choose the resources and agents, then review the preview and apply.

Measure

Command	Purpose
`usage [--by session\|skill\|project\|model\|day\|agent] [--since 30d] [--until day] [--agent claude-code\|codex\|all] [--project root]`	tokens, cache hit rate and cost estimate from local Claude Code and Codex transcripts; see Usage
`prune`	propose unused skills (never deletes)
`reflect [--since 30d] [--top 5] [--project root] [--no-write]`, `reflect show <session>`, `reflect lessons`, `reflect lesson add\|verdict\|dismiss`	rank struggling sessions, write redacted trajectories and keep lessons; see Reflect
`context [--mode potential\|catalogue] [--agent claude-code\|cursor\|codex] [--scope global\|project]`	estimated instruction size; see Context map
`bench scaffold\|run\|compare\|arena`	local A/B runs of two configurations; see Benchmarks

Command	Purpose
`share`, `apply`, `revoke`	see Sharing
`loadouts list\|show\|install`	composed sets of resources from your sources (`source/name` when names collide)
`retrofit`	detect the stack and generate a project contract
`git status\|pull\|push`	delegated Git (fast-forward pull, never force push)

Account and teams

Command	Purpose
`auth login [--service <url>] [--no-browser]`	browser sign-in (GitHub or Google); the API token goes to the OS keychain
`auth status`, `auth logout`	show or revoke the current sign-in
`auth tokens`, `auth revoke <token-id>`	list or revoke your API tokens
`team list\|create\|members`	teams (Clerk Organizations)
`team invite <org> <email> [--role admin\|member]`	Clerk emails the invitation
`team invitations <org>`, `team cancel-invitation <id>`	invitations you sent (admins)
`inbox` (or `team inbox`), `team accept\|reject <id>`	invitations for you
`team role <org> <user> admin\|member`, `team remove`, `team leave`	membership changes
`team shares <org>`	shares published to a team

auth login opens your browser on the Preflight sign-in page and listens on 127.0.0.1 for the redirect. With --no-browser, it prints the URL and you paste the code that the page shows. Tokens expire after 90 days without use.

Backend setup: Cloudflare backend and accounts.

Environment

Variable	Used for
`PREFLIGHT_HOME`	default harness home
`PREFLIGHT_API_URL`	the backend (default `https://api.preflight.arhun.fr`)
`PREFLIGHT_SHARE_URL`, `PREFLIGHT_SHARE_TOKEN`	share with an explicit service and API token instead of the signed-in account
`PREFLIGHT_METRICS`	a benchmark task writes tokens, interventions, cost, model and any limit reached here
`PREFLIGHT_BENCH_MODEL`, `PREFLIGHT_BENCH_EFFORT`, `PREFLIGHT_BENCH_BUDGET_USD`	the model, effort and budget a benchmark run asks a task to use

Worked examples for each group: PREFLIGHT.md.

Output formatCopy Anchor Link

StatusCopy Anchor Link

Setup and stateCopy Anchor Link

Inspect and adoptCopy Anchor Link

Change resourcesCopy Anchor Link

Find and installCopy Anchor Link

Install from a repositoryCopy Anchor Link

MeasureCopy Anchor Link

Share, project and GitCopy Anchor Link

Account and teamsCopy Anchor Link

EnvironmentCopy Anchor Link

On this page