CLI Reference#

Complete reference for all Osprey Framework CLI commands.

Prerequisites: Framework installed (uv sync)

Overview#

All commands are accessed through the osprey command.

A deployment is a git repository: profile.yml at its root is the source you edit, build/ is what a build renders from it, and var/ is durable state. The lifecycle verbs find that repository by walking up from wherever you are standing, so none of them has to be told where it is; --repo DIRECTORY names another one explicitly.

osprey --version          # Show framework version
osprey init               # Create a deployment repo from a preset
osprey set KEY=VALUE      # Write a setting into profile.yml
osprey validate           # Check profile.yml without building
osprey build              # Render build/ from profile.yml
osprey up                 # Start the deployment, as built
osprey down               # Stop it, keeping all data
osprey restart            # Stop and start it again
osprey status             # Show what it is doing
osprey logs               # Show its container logs
osprey reset              # Wipe it back to a fresh state
osprey config             # Show the deployment configuration
osprey chat               # Talk to this deployment's agent
osprey query              # Send one prompt to the agent, print the answer, exit
osprey users              # Manage web-terminal users
osprey write-authorization # Approve, list and revoke programs' write authorizations
osprey feedback           # Read feedback sent from the web terminals
osprey profile            # Validate and inspect build profiles
osprey health             # Check system health
osprey channel-finder     # Channel finder CLI
osprey knowledge          # Facility knowledge bundles and graph corpus
osprey facility           # Check and show the facility description under data/facility/
osprey app                # Make and check a deployment's apps
osprey sim                # Simulation scenario commands
osprey ariel              # ARIEL logbook search service
osprey archive            # Copy artifacts and plan-queue history into var/archive
osprey history            # Serve the history page (the history service's entry)
osprey agent-record       # The agent record: serve it, check its health, run its export
osprey web                # Launch web terminal
osprey theme-lab          # Design and preview a theme in the browser
osprey scaffold           # CI files, boot unit, build artifact overrides
osprey audit              # Audit project or profile safety
osprey watchdog           # Try safety watchdogs on labelled prompts
osprey vendor             # Manage locally bundled vendor assets

Global Options#

--version

Show framework version and exit.

-v, --verbose

Show debug output, including every container command run. The transcript takes the place of the progress report rather than joining it, so under -v no phase or step lines are printed at all. Without it, a run prints the progress report and the command’s own output only; log records below WARNING never reach the screen, though they still reach every sink the deployment configures.

--help

Show help for any command (e.g., osprey build --help).

osprey init#

Create a deployment repository from a bundled preset.

osprey init [DIRECTORY] --preset NAME [OPTIONS]

DIRECTORY is the repository the deployment lives in. Omit it to initialize the current directory in place, which is how a repository cloned empty from a forge is filled in.

The directory’s name is proposed as the deployment’s name: osprey init normalizes it to a valid compose project name and records it in profile.yml as project_name:, beside the display name:. That tracked value names the compose project, volumes, images and login renders on every host from then on; the folder a later clone sits in plays no part. Change it in profile.yml, or with osprey set project_name=NAME, before the first osprey up if the folder name is not the name you want (Build Profile — profile.yml).

The repository holds four zones — source you edit, secrets, disposable build output, and durable state:

DIRECTORY/
  profile.yml                    the manifest; everything the preset configures
  providers.yml                  the model-provider catalog `provider:` picks from
  data/ tiers/ apps/ triggers.yml  the material it names — yours to edit
  .env                           provider keys, seeded from your shell
  build/                         rendered by `osprey build`; gitignored
  var/                           agent memory and audit log; gitignored

git init and an initial commit run at the end, unless a git repository already encloses the target or --no-git is given.

--preset NAME — Bundled preset to materialize.

--list-presets — List bundled preset names and exit.

--set KEY.PATH=VALUE — Edit the emitted profile (repeatable): the value at KEY.PATH is replaced, whatever the preset holds there — a list you state is the list the profile holds. The same edit osprey set makes once the profile exists. RHS is parsed as YAML, so [] and null are values. Top-level shorthands: provider, model, channel_finder_mode, connector, port_base (move the whole deployment onto another thousand-port block, e.g. --set port_base=42000 — handy for a second stack beside one already on the default 10000 block).

--force — Re-materialize the source zone of an existing deployment repository, discarding edits to profile.yml, data/, tiers/, apps/, triggers.yml, web-terminal-context/, watchdogs/, and .env.example. In providers.yml the entries OSPREY ships are reset to the packaged values and the ones you added are kept. Never touches .env, .git, var/, build/, .gitignore, .env.shared, README.md, ci-extra.yml, the CI file, scripts/verify.sh, mcp_servers/, or rules/.

--reset — Start over on a name used before. Deleting a deployment’s directory leaves its containers and data volumes behind, because they are keyed on the project_name: a repository re-created under that name meets them, and its first osprey up refuses to start while an old store would reject the freshly minted credential. --reset makes the removal osprey reset --yes makes (the containers, data volumes and images, and, when the repository still exists, the agent’s memory, build/ and the tokens minted into .env), then re-materializes the source zone as --force does. The data is lost, and nothing asks you to confirm. It refuses up front when no container runtime answers. To keep the old data instead, pass --reuse-stores to osprey up.

--no-git — Skip git init and the initial commit.

--revalidate [--preset NAME] — Bring an existing deployment repository to this OSPREY in place: the current profile vocabulary, what the presets changed since the repository last took them, the provider entries and keys OSPREY added since (every value already in providers.yml is kept), and, while the profile’s lists name nothing by path, the repo’s own skills, agents, rules, output styles and hooks named by path in profile.yml and each lists: own login (a bare entry the repo ships a file for becomes its path), so every render keeps what it carried. A preset change is applied only where your file still holds the preset’s old value: an added key, panel or step you lack is added, and a removed or changed one you kept is removed or updated. Anything you changed yourself is left alone, and a key, entry or provider you deleted is not added back. What it does not apply but you may want is printed once, under “left for you”. Drop any change you do not want from the diff before you commit: it is not offered again. --preset NAME switches the profile to that preset and fills in what it has and the profile lacks. A repository made before this tracking existed starts it on its first --revalidate: nothing records what its presets said, so that run fills in the config: keys the profile lacks and lists whatever else differs from the presets under “left for you”, applying none of it. A login file left in apps/ moves to tiers/<name>.yml: one never edited is re-emitted from the bundled login, an edited one keeps its lines and gains lists: own and, unless it states its writes, control_system.writes: never; where the tiers/ file already exists, the output says to merge the two by hand. A landing.groups entry type: apps becomes type: shared; until then it reads as shared for one release. Your deployment’s own selections — the roster, the shared logins, the default tier, role tiers, the landing groups — are left for you and named in the output. Retired write keys are rewritten to the tier key control_system.writes in every layer (Upgrading from a deployment-wide write flag), and retired per-tool policies for switch-governed tools are removed. Prints a diff to review and commit.

The step is one-way: an older OSPREY refuses the revalidated repository. To go back, check out the repository as it was before the commit and install the previous release.

--up / -d, --detach / --dev — Build and start the deployment right away, optionally in the background or in development mode.

osprey init --list-presets
osprey init my-assistant --preset demo
osprey init demo --preset demo --up -d --dev
osprey init my-assistant --revalidate

osprey set#

Write settings into the deployment profile.

osprey set KEY=VALUE... [--repo DIRECTORY]

Each KEY=VALUE is written into this repository’s profile.yml in place, comments intact. That file is the source of truth, so this is the only command that edits configuration for you — the rendered build/config.yml is generated from it and is never hand-edited. Run osprey build to carry a setting through to build/, then osprey up to deploy it.

KEY is a top-level profile key (provider, model, channel_finder_mode, connector) or a dotted path. Keys under config. address the rendered config: config.control_system.type=epics writes that literal dotted entry into the profile’s config: block. VALUE is read as YAML, so true/false become booleans and bare numbers become numbers.

channel_finder_mode names the channel-finder paradigm the build renders: in_context, hierarchical, middle_layer or graph. The first three search a channel database file; graph searches the graph store named by services.graphdb – deployed with the stack or facility-hosted – instead of a database file.

One shorthand stands in for a longer key path: connector= writes config.control_system.type. It takes the built-in types epics, virtual_accelerator, doocs, tango and live_standin; whether the simulator runs in process is set by config.control_system.connector.virtual_accelerator.serving. (Control systems beyond the bundled ones are reachable through custom connector packages — see Use Connectors.) An EPICS gateway is written by its own dotted keys, which is the only spelling: OSPREY ships no table of facilities’ gateway addresses.

osprey set model=claude-sonnet-5
osprey set connector=epics
osprey set channel_finder_mode=in_context
osprey set config.system.timezone=America/Los_Angeles
osprey set config.control_system.connector.epics.gateways.read_only.address=gw.example.org
osprey set --repo ~/my-assistant config.control_system.writes=never

osprey set only lowers the write ceiling; raise it in the profile or tier file.

osprey validate#

Check the deployment profile without building.

osprey validate [TARGET] [--repo DIRECTORY]

With no argument, validates the deployment repository enclosing the working directory. TARGET names a different profile to check instead — a login file under tiers/, or a directory holding a profile.yml.

Resolves extends: chains and runs the full consistency check — convention directories, the data: tree, service templates, lifecycle steps, env vars — then lints the declared web stack against the config a build would render. Every problem found is reported, not just the first. Exits 0 when the profile is valid, 2 with the accumulated errors when it is not, so a CI job can gate on it.

The profile is yours to edit, so no difference from the preset osprey init wrote it from is refused or listed, in profile.yml, a login file, or providers.yml. When the bundled preset has changed since, validate and osprey build print one line saying so.

osprey validate
osprey validate tiers/readonly.yml
osprey validate --repo ~/my-assistant

osprey config#

Show the deployment configuration.

osprey config [--rendered | --defaults] [--repo DIRECTORY]

With no flag, prints the source profile.yml — the tracked, hand-edited manifest — exactly as it is on disk, comments included. Output is piped through unchanged when stdout is not a terminal. This command only reads; to change a setting, use osprey set.

--rendered — Show the built config.yml the deployment actually runs on.

--defaults — Show every key the framework reads and the value it falls back to when profile.yml does not spell that key. Needs no deployment repository.

--defaults prints a ledger, not a template to copy: one line per key, in full dotted form, grouped by top-level block, with the comment above each key saying where the answer comes from. Every answer was read out of the code that reads the key, so it is what actually happens when a line is absent — which is the question a preset cannot answer, because a preset shows a value. A key with a literal default prints it as YAML; where there is no literal, a marker stands in:

Marker

Meaning

<required>

No fallback exists and none may be invented. A deployment’s profile.yml has to spell this key.

<derived>

Computed when the key is read. The comment above the key names what it is computed from.

<no fallback>

The reader supplies none: it raises, or nothing reads the key yet, or “unstated” is deliberately not “false”. The comment says which.

<covered by KEY>

The leaf has no reader of its own, so KEY carries the default that covers it. With no enclosing key in the ledger this reads <no separate default>.

osprey config
osprey config --rendered
osprey config --defaults | less
osprey config --defaults > defaults.yml

osprey profile#

Validate and inspect build profiles. The profile is the durable, facility-owned source a deployment is built from — see Build Profiles.

osprey profile validate TARGET
osprey profile presets
osprey profile artifacts
osprey profile card
osprey profile validate TARGET

Check a profile without building anything. TARGET is a directory holding a profile.yml or a path to a profile file. Resolves extends: chains and reports every problem found — convention directories, the data: tree, service templates, lifecycle steps, env vars. Exits 0 when valid, 2 with the accumulated errors when not. Inside a deployment repository, plain osprey validate checks that repository without naming a target.

osprey profile presets

List bundled preset names, one per line. Every name printed is usable as --preset NAME for osprey init.

osprey profile artifacts

List every artifact the six profile lists can name — hooks, rules, skills, agents, output styles, and web panels — with a one-line description of each. The same menu appears as commented entries in an emitted profile.

osprey profile card [--json] [--repo DIRECTORY]

Print the composition card osprey init prints, for a repo that already exists: who can sign in and with what rights, what the agent runs on, what machine it talks to, and what runs beside it. It reads profile.yml and the login files beside it; nothing is built, started or probed. --json prints the rows as one JSON array of {group, label, value} objects on stdout and every warning on stderr.

osprey profile presets
osprey init my-facility --preset demo --set model=claude-opus-5
cd my-facility
osprey validate
osprey build

osprey build#

Render this deployment repository’s build/ from its profile.

osprey build [OPTIONS]

Run it with no arguments, anywhere inside a deployment repository. It walks up to the repository’s profile.yml and renders the whole output zone from it: config.yml, the OSPREY agent artifacts, the data tree, the service templates and the compose files that deploy them.

build/ is derived in full and holds nothing durable — your keys are in .env, the agent’s memory is in var/ — so every build wipes and re-renders it. The render lands in build/.tmp and replaces build/ only once it has succeeded, so a build that fails, or one you interrupt, leaves the previous build exactly as it was and still able to stop the stack it started.

It renders files, never containers: rebuild while the stack is up and the change takes effect at the next osprey up or osprey restart.

-s, --stream — Stream lifecycle step output in real time.

--skip-lifecycle — Skip the profile’s pre_build, post_build, and validate steps; deployment-package wheels are still built and installed.

--skip-deps — Skip venv creation and dependency installation (CI mode); deployment-package wheels are still built, for the image. Building a wheel runs the package’s own build code, which can read HOME and PIP_*/UV_* variables.

--runtime-root PATH — Override project_root in the rendered config, for a build whose output runs somewhere other than where it was made.

--dev — Render a dev build: bake the local osprey checkout into the service images instead of the published release. osprey up --dev starts it.

--repo DIRECTORY — Deployment repository to act on (default: the nearest profile.yml at or above the working directory).

osprey build
osprey build --repo ~/deployments/my-assistant
osprey build --skip-lifecycle --skip-deps          # CI: no venv, no hooks

Lifecycle verbs#

osprey up, down, restart, status, logs and reset run the deployment’s container stack. Each one takes --repo DIRECTORY and otherwise needs no arguments: run it anywhere inside the deployment repository.

osprey up#

Start this deployment from build/, as built.

It starts what the last osprey build rendered and re-renders nothing from profile.yml, so the services that come up are always the ones you can read on disk. It reads profile.yml for one thing: a fingerprint. If the profile has changed since the build, up refuses and says what moved, because starting would deploy something other than what the profile now describes.

One exception, by design: a deployment with web terminals re-renders that stack at every start — its compose file, nginx config, landing page, and any login whose project is missing. Those follow the user roster rather than the build, so a roster edit takes effect on the next start.

Before it touches a container, up checks who created the ones already running under this deployment’s project_name. It refuses when containers named for this project were created from another checkout of the repository — a second clone or worktree on the same host reads the same tracked name — and names that checkout. Nothing is deployed. Either stop the deployment where it lives (osprey down --repo <that checkout>), or give this copy its own name in a variant overlay:

profiles/scratch.yml:   project_name: <project_name>-scratch
.env.variant:           OSPREY_PROFILE_VARIANT=scratch

then osprey build and start again (Two checkouts of one repository on one host). Containers with no checkout label count as this deployment’s. osprey restart runs the same check before it stops anything.

Whether the deployment is reachable off-host is a property of the build, not of this command: the bind address is rendered into every published port. Change it with osprey set config.deployment.bind_address=0.0.0.0, then rebuild.

-d, --detached — Run services in the background.

--dev — Start the dev render, with freshly built images running the local osprey checkout instead of the published release. Needs a dev build (osprey build --dev), or --build to chain one.

--build — Re-render build/ from profile.yml first, then start it.

--as-built — Start build/ as it was rendered, even though profile.yml has moved on.

--keep-archiver-base — Keep the existing archiver history even when the profile’s retention/cadence knobs no longer match it. Without it, changed knobs rebuild the base series and discard recorded samples.

--reuse-stores — Adopt the data volumes an earlier deployment of this name left behind, keeping their contents: each store’s original credential is restored to .env in place of the one just generated. Only possible while the store’s container survives.

osprey down#

Stop this deployment, keeping all data. It renders nothing; destroying data is osprey reset, which asks first.

If build/ is gone or was never rendered, down does not re-derive the compose files from profile.yml — those describe what would be started now, not what is running. Instead it stops the containers this repository labelled as its own, which is the recovery path for a build/ deleted while the stack was up. Containers are labelled when they are created, so a stack started before this labelling existed cannot be found that way; run osprey build to restore build/ and down works normally again.

osprey restart#

Stop and start this deployment again. Takes the same options as up: -d/--detached, --dev, --build, --as-built, --keep-archiver-base, --reuse-stores. --reuse-stores is checked before the stop, since stopping removes the containers it reads from. The stop half acts on the runtime and compose project the last osprey up recorded; the start half picks the runtime the setting selects now.

osprey status#

Show what this deployment is doing. It reads and reports — it starts nothing, stops nothing and renders nothing — so it is safe to run against a live stack at any time.

Five sections. Build says whether build/ still matches profile.yml, the same check osprey up refuses on, and which version of osprey rendered it. Containers is what the container runtime reports, not what compose thinks should exist. Endpoints is where the services are declared to answer. Writes lists each login’s tier and switch positions. Agent is the provider, whether its credential can be found, and whether the rendered agent files still match the config.

--agents — Also show the per-subagent model assignments.

osprey logs#

Show this deployment’s container logs, and step out of the way: -f streams, Ctrl-C stops it, piping into other commands works, and the exit code is the runtime’s own. Both halves of a deployment are covered — the services and, when there is one, the web-terminal stack.

-f, --follow — Keep streaming new output until interrupted.

--tail INTEGER — Show only the last N lines per container.

osprey logs
osprey logs event-dispatcher -f
osprey logs --tail 50

osprey reset#

Wipe this deployment back to a fresh state. It stops the stack, removes the containers, volumes and images of this deployment, destroys the agent’s memory under var/agent_data/, strips the tokens osprey up minted out of .env, and deletes build/ and var/deployment.json.

What survives, the plan lists before you confirm:

  • var/audit/ — the audit files written before the agent record;

  • var/agent_record/ — the agent record, with var/spool/ feeding it and, on the ClickHouse backend, the record’s data volume (<project>_agent_record_clickhouse_data);

  • var/archive/ — the archive: the record’s daily exports, with the artifact and Bluesky copies beside them;

  • var/state/ — each identity’s locks, leases and markers;

  • everything in .env that a deploy did not mint — your provider keys.

The source zone is never touched: profile.yml, data/, tiers/, apps/, triggers.yml and .git are exactly what they were.

Reset refuses, touching nothing, while a host osprey web, chat or query is running the agent record locally, and names those sessions.

What belongs to this deployment is decided two ways. A container records the checkout that created it in a label, and reset refuses outright — removing nothing — when containers under this project_name were created from a different checkout; it names that checkout so you can reset from there. A container with no label at all counts as this deployment’s. Volumes carry no such label: they belong to the project by name (<project_name>_<volume>), so once the containers check out, every volume under that name is removed, except the record’s data volume a plain reset keeps.

--dry-run — Show the removal plan and stop. Nothing is stopped, removed, or written.

-y, --yes — Skip the typed confirmation. The plan is still printed.

--purge-audit — Also destroy the agent record and the audit files from before it: var/audit/, var/agent_record/, var/spool/, the record’s ClickHouse volume, and the record’s exports in the archive (var/archive/<day>/agent_record/), marking each purged day in its manifest. All are kept by default. var/state/ and the rest of var/archive/ are kept either way.

Exit status: 0 the reset did what it said (or there was nothing to do), 1 you declined or it refused, 3 it ran but the deployment is only partly reset, with each survivor named above the exit.

osprey up -d
osprey status
osprey up --build -d
osprey restart --dev
osprey logs -f
osprey down
osprey reset --dry-run

osprey users#

Manage this repository’s web-terminal users. A multi-user deployment gives each person on the roster their own web terminal, container and workspace volumes; these verbs act on that roster, which lives in the profile. Every verb takes --repo DIRECTORY.

Verb

What it does

Also accepts

remove USER

Retire one person: remove their web-terminal workspace.

--archive, --purge, -y/--yes

prune

Remove workspaces for people no longer on the roster.

--archive, --purge, -y/--yes, --dry-run

seed [USER]

(Re)seed workspaces from the roster; USER targets one person, omit to reseed all.

—

passwd USER

Change one user’s login password (password authentication only). Prompts without echoing, and ends that user’s sessions.

—

list [USER]

Show every card, what it runs and who may open it, with a grid of logins against shared cards. Name a login for what it may open, or a card for who may open it. Reads only.

--json, --live

login-url USER

Print the URL that opens that user’s terminal under auth.method: token. Only the URL goes to stdout, so it can be piped or copied. Refuses for a user who signs in through a login page, and for every user of an open deployment.

—

env

Render .env.users, the env file every per-user container runs with.

--env-file, -o/--output

--archive – Archive a user’s workspace before removing it (mutually exclusive with --purge).

--purge – Permanently delete a user’s workspace without archiving it (mutually exclusive with --archive).

-y, --yes – Assume yes to confirmation prompts.

--dry-run – Show what would happen without making changes.

osprey users list joins the rendered roster, shared logins and each render’s control_system.writes by the rules the render and the login service apply. --live adds container state and last sign-in from the running stack; off the host, or with the stack down, those read as a dash. Sign-ins come from the agent record, in UTC, so a dash there means the record holds none, not that the person never signed in. The grid appears only under password and oidc, the two methods that enforce access; under none and token the command says what opens a card instead.

osprey users login-url builds the URL from that user’s operator secret in the repository’s .env, which osprey up mints for every roster user in every auth mode. Opening it once trades the token for a session cookie. It is how someone gets in under auth.method: token, the default, where nginx stamps no credential on the request — and it is a password: send each person only their own. Rotate one by deleting that user’s OSPREY_TERMINAL_SECRET_* line from .env and running osprey up again.

The command refuses in the two cases where the URL would accomplish nothing, rather than putting a live credential in someone’s inbox for it. A user behind a login page (password/oidc) is named their login page instead: the authentication service turns the request away before the terminal can read the token. A user of an open deployment (auth.method: none) is named their terminal’s plain address instead, because nginx vouches for that terminal on every request and there is no token to trade.

osprey users env renders the same subset a deploy would generate, from the same two inputs — the rendered deploy config and the repository root’s env chain (.env.shared then .env, so .env wins on a key both set) — so a file rendered here and one generated by osprey up cannot disagree. Values come only from those files, never from the surrounding environment. --env-file PATH renders from that one file instead of the chain. -o/--output PATH writes the result at mode 0600 instead of to stdout, replacing whatever is there. A deploy re-renders only a .env.users it rendered itself and never touches one you have edited by hand — but it refuses to start when such a file disagrees with .env on a provider key, and this verb is the remedy it names. In CI, pass --output: without it the assembled secrets go to the job log.

osprey users remove alice --archive
osprey users prune --dry-run
osprey users list
osprey users seed alice
osprey users passwd alice
osprey users login-url alice
osprey users env --output .env.users

See Deploy a Facility for the walkthrough that uses these verbs end to end.

osprey write-authorization#

Approve, list and revoke a program’s bounded write authorization without a web terminal (see Writing from a program). Inside a deployment repo, or with --repo DIRECTORY, the verbs act on the deployment’s control-context tree as the login a request names, and read the requests from var/write_ledger/requests and, for a program run on the host, from each login’s own authorizations/requests. Outside a deployment they act on this account’s own state directory: the owner is this account, as on a laptop with no terminal.

Verb

What it does

Also accepts

approve REQUEST

Show a request (a file, or its id) and approve it: the grant is written under the owner’s record lock, with approver.identity this account and surface: "cli". Refused, with nothing written, for a target the deployment does not configure, a never or unknown tier (judged as the program’s own writes will be: by the staged login map for a request in var/write_ledger, by the rendered config for one filed on the host), a range outside the limits database, a channel with no numeric range there, and a channel another program of the same owner holds (auth_overlap).

--owner LOGIN, --config FILE, --yes

list

The requests waiting for approval and the authorizations, each in force or not, with the steps used of the total; one whose steps are used or whose lease lapsed is not in force. A program’s self-issued grant, written at allowed into var/write_ledger, is listed too, marked self-issued. Grants that ended over an hour ago are pruned.

--owner LOGIN, --json

revoke ID

Mark one authorization revoked, a self-issued one included; the holder’s next write is refused.

--owner LOGIN

osprey write-authorization list
osprey write-authorization approve 3f2a…9c1e
osprey write-authorization approve ./request.json --yes
osprey write-authorization revoke 3f2a…9c1e

osprey feedback#

Read the feedback this deployment’s web terminals collected. People using a web terminal can send a report from the terminal itself; each submission is stored with the session it was sent from, in the sender’s own workspace, and these verbs read it back. Every verb takes --repo DIRECTORY.

A multi-user deployment keeps one store per person, and reading it starts a short-lived read-only container on each person’s workspace — so the deployment’s container runtime has to be up. A single-user deployment keeps one store on this machine, read straight off disk.

Verb

What it does

Also accepts

list

One line per submission, newest first: id, who sent it, when (UTC), which channel it went out on, and the start of the message. Headers only.

—

export

Every submission’s whole record plus the session captured with it, as one JSON array. Written a record at a time, so a large store never has to fit in memory.

-o/--output

-o, --output PATH – Write the export to this file instead of stdout. Naming a directory, or a file inside a directory that does not exist, is a usage error at parse time, before any workspace is read.

With no --output, export puts the JSON document on stdout and nothing else, so it can be redirected straight into a file; errors and the closing summary go to standard error. With --output, the human output stays on the terminal and the file holds the export. An empty store exports [].

A workspace that cannot be read is reported and the rest of the deployment is still listed or exported; the export’s closing summary distinguishes a workspace that contributed nothing from one that was only partly readable. If nothing at all could be read, both verbs stop rather than reporting a deployment with no feedback in it.

Exit status: 0 on success, including a deployment nobody has sent feedback from. Non-zero when the repository has no build, when every workspace failed to read, and when an export stopped part-way — in which case the file still parses and holds what was read.

agent_data.base_dir is checked on the single-user path only, and a ~-relative value there is non-zero with the explanation (the data lands where the verb cannot reach it). The multi-user path never consults the key: it mounts each person’s volume and reads a fixed path inside it, so a rostered deployment with a ~-relative agent_data.base_dir writes its feedback to a volume these verbs do not mount and simply reads as having none. Nothing detects that, so do not read an empty multi-user listing as proof. See Send and Retrieve Feedback.

osprey feedback list
osprey feedback list --repo ../other-deployment
osprey feedback export --output feedback.json
osprey feedback export > feedback.json

See Send and Retrieve Feedback for the dialog these records come from and what each submission carries.

osprey health#

Run comprehensive system health check.

osprey health [OPTIONS]

--project DIRECTORY – Deployment repository or rendered project directory (default: the repository enclosing the current directory).

-v, --verbose – Show per-warning and per-error details in the summary.

--json – Emit the report as a single JSON document on stdout.

--category NAME – Run only the named category (repeatable).

--full – Also run on-demand categories (live model chat, pinned CLI download).

Exit codes: 0 healthy, 1 warnings only, 2 one or more errors, 3 the command itself failed, 130 interrupted. See The osprey health --json Contract for the --json document’s shape and the jq patterns for consuming it, and Configure Health Checks for the health: config block.

osprey archive#

Copy the artifact stores of web terminals and dispatch workers and the plan-queue history into an append-only archive, beside the agent record’s own daily export. See The Agent Record.

osprey archive --sources DIRECTORY --dest DIRECTORY [OPTIONS]

--sources DIRECTORY – Sources tree, <sources>/<kind>/<name>/... (environment: OSPREY_ARCHIVE_SOURCES).

--dest DIRECTORY – Existing archive root the day directories are written into (environment: OSPREY_ARCHIVE_DEST).

--once / --watch – Run one pass and exit (default), or run a pass at once and then every --interval seconds.

--interval SECONDS – Seconds between passes under --watch, at least 60 (environment: OSPREY_ARCHIVE_INTERVAL_SECONDS, default 86400).

Exit codes of --once: 0 the pass completed with no errors, 1 it completed with recorded errors, 2 it could not run (the destination is missing or unwritable). --watch exits 2 after five passes in a row that could not run.

osprey history#

Serve the history page: the across-users view of the agent record, which the deployment renders as the history service when its web terminals sign people in (auth.method of password or oidc). Browsers reach it under /history/ on the history page’s origin only; the command is the service’s entry and is not run by hand.

osprey history [--host HOST] [-p, --port PORT]

--host HOST – Interface to listen on (default 127.0.0.1; the service listens on every interface of its container).

-p, --port PORT – Port to serve on (default 8000).

The page reads the agent record at OSPREY_AGENT_RECORD_URL with the record’s history login (OSPREY_AGENT_RECORD_LOGIN), naming the viewer the sign-in resolved; the record decides what that viewer sees. It admits only requests that carry the gate secret nginx presents (OSPREY_TERMINAL_SECRET_HISTORY).

osprey watchdog#

Try safety watchdogs out before relying on them. Safety watchdogs has the steps, including the format of a fixture.

osprey watchdog replay#

Replay labelled prompts through watchdogs, enabled or not, and report how each did. Nothing is flagged, held or recorded.

osprey watchdog replay FIXTURES_DIR [--watchdog NAME] [--profile DIR ...] [--project-dir DIR]

FIXTURES_DIR holds *.jsonl fixtures at any depth, and each directory is one set. Definitions come from each --profile, by default from the project’s profile. Agent watchdogs need a built project through --project-dir and are reported as not run without one. A fixture’s machine values are written to that project’s in-process simulator under its usual write checks; a fixture they cannot apply to is reported as not run, and no other control system is written.

For each watchdog, engine and set it prints the hit rate on risky prompts, the false-flag rate on benign prompts, p50 and p95 latency, and cost. The exit status is non-zero only when an engine answered on none of its fixtures.

osprey agent-record#

The agent record: the one store of every session fact the deployment’s agents produce. Every deployment renders it as the agent-record service; see The Agent Record for how long it keeps an entry and how to check on it.

osprey agent-record serve#

Serve agent-record: it ingests the spool every source appends to and the Claude Code transcripts mounted into it, writes them to the configured backend (agent_record.backend), and answers reads for the credentials the deployment minted. The command is the service’s entry and is not run by hand.

osprey agent-record serve [--host HOST] [--port PORT] [--lease-dir DIRECTORY]

--host HOST – Interface to listen on (default 127.0.0.1; the service listens on every interface of its container).

-p, --port PORT – Port to serve on (default: the configured agent_record.port).

--lease-dir DIRECTORY – Run as the host-local record that host commands start when no stack runs one: report ready only after the first full ingest pass, and stop once no lease in this directory names a live process.

It reads the verifier and the secret set, and the spool, record and transcript locations, from the environment its compose service renders.

osprey agent-record health#

Show the agent record’s health: every spool source and transcript root (live, idle or stopped, its backlog, refusals and errors), the backend, and how far the export to the archive is behind. It waits for the record’s start-up job run to finish, then answers, and names each problem it finds.

osprey agent-record health [--repo DIRECTORY]

It reads the record OSPREY_AGENT_RECORD_URL names; with no stack up and no host session, it starts the host-local record for the call and stops it again afterwards. A project whose agent_record.backend is clickhouse needs its stack: with nothing up the command refuses and names osprey up.

osprey agent-record export#

Run the catch-up export now: every closed day the archive does not hold yet is written to var/archive/<day>/agent_record/. It waits for the record’s start-up job run to finish, then prints the days this call exported and the latest exported day.

osprey agent-record export [--repo DIRECTORY]

It opens the record the same way osprey agent-record health does.

osprey chat#

Talk to this deployment’s agent. See Run the Agent from the Command Line.

osprey chat [PROMPT] [OPTIONS]

Starts the agent in the deployment’s build/ directory, wired to the provider, control system and facility knowledge that build was rendered with. PROMPT, when given, is the opening message — with --print it is answered and the command exits, which is the shape a script wants.

Nothing is re-rendered: osprey build owns that. When the profile has changed since the last build, a warning says so and the session starts anyway against the build as it stands.

--resume SESSION_ID — Resume a previous agent session by ID.

--print — Print the answer and exit.

--effort [low|medium|high|max] — Reasoning effort (default: claude_code.effort from the build).

--no-pin — Ignore claude_code.cli_version and use the installed agent CLI.

--repo DIRECTORY — Deployment repository to act on.

osprey chat
osprey chat --print "what is the stored beam current?"
osprey chat --resume abc123
osprey chat --repo ~/my-assistant

osprey query#

Send a prompt to this deployment’s agent, print the answer, and exit. See Run the Agent from the Command Line.

osprey query PROMPT [OPTIONS]

Runs read-only: write, execute and destructive tools are blocked at the agent SDK level, so the command is safe in CI pipelines and automated workflows. It asks the deployment enclosing the current directory, answering from its build/ as it was last rendered. When profile.yml or a file it points at has changed since that build, a warning on stderr says so and the query runs anyway.

--json — Emit a JSON object with final_text, tool_traces, mcp_servers and exit_code on stdout.

--repo DIRECTORY — Deployment repository to act on.

Exit codes: 0 the agent completed and every expected MCP server connected, 1 the verdict failed (a server was missing from the session, the agent returned an error result, or the run hit its cost or turn budget), 2 a usage error (nothing built to answer from, the agent SDK is not installed, or the provider is not configured).

osprey query "What PVs are used for beam current?"
osprey query --repo ~/my-assistant "List vacuum sections"
osprey query --json "Summarise recent alarms"

osprey channel-finder#

Tools for validating, previewing, serving and benchmarking control system channel databases.

Options: --project PATH, -v, --verbose

osprey channel-finder validate [-d, --database PATH] [--pipeline hierarchical|in_context|middle_layer] [-v]

Validate a channel database JSON file. --pipeline names the paradigm: the file is read as that paradigm, and without --database it is the one at channel_finder.pipelines.<pipeline>.database.path — the command refuses, naming that key, when it is unset. Without --pipeline the paradigm is auto-detected from the project’s config.

osprey channel-finder preview [--depth N] [--max-items N] [--sections LIST] [--focus PATH] [--database PATH] [--full]

Preview a channel database as a tree; the paradigm is auto-detected from the project’s config. --depth is the tree depth to display and --max-items the most items shown per level (both default 3; -1 for unlimited). --sections is a comma-separated list of tree, stats, breakdown, samples or all (default tree). --focus shows one path only (M:QB for the QB family in the M system). --database reads that file instead of the configured one, and --full shows the complete hierarchy (--depth -1 --max-items -1).

osprey channel-finder benchmark --model PROVIDER/WIRE_ID [--queries SPEC] [--runs-per-query N] [--concurrency N] [--output-dir DIR] [--queries-path PATH] [-v]

Run the benchmark harness against a channel-finder pipeline using a LiteLLM-form model id (e.g. anthropic/claude-haiku-4-5). Saves per-run JSON results for accuracy/cost analysis.

A graph-mode project has no channel database file: validate and preview say so and point at osprey build && osprey up and the read_cypher tool, and --pipeline does not offer graph for the same reason.

osprey channel-finder validate
osprey channel-finder preview
osprey channel-finder benchmark --model anthropic/claude-haiku-4-5

osprey knowledge#

Maintain the facility’s OKF bundle of concept documents. An omitted BUNDLE comes from facility_knowledge.bundle_path. The graph store and the channel search index have no verb of their own: osprey build writes the graph view data/graph/facility.ttl and the index from the facility file, and osprey up seeds the store from that view. See The OKF Bundle and Search the Facility Graph.

osprey knowledge regen-index [BUNDLE]

Regenerate the index.md files throughout an OKF bundle. Run it twice and the second run changes nothing.

osprey knowledge validate [BUNDLE]

Check every document in a bundle against the OKF format, including each index.md against its directory.

osprey knowledge seed-from-ttl BUNDLE [--ttl PATH] [--force] [--repo DIRECTORY]

Write stub concept documents into a bundle from the build’s graph view, one per device, for a person to fill in. The view read is build/data/graph/facility.ttl in the deployment repo you stand in or --repo names; --ttl names another Turtle file. Each stub’s device_id is the facility file’s device id, so the build links the page to its device.

osprey knowledge seed-from-ttl data/facility/knowledge
osprey knowledge validate

osprey app#

Make and check a deployment’s apps without building anything; the walkthrough is Build Your Own OSPREY Apps.

osprey app new NAME [--force] [--repo DIRECTORY]

Copy the shipped scaffold — one container, a panel with a state route, one read tool, one approval write tool — into apps/NAME/; it passes osprey app check as copied. Its names are rewritten to NAME (the Python package to NAME with underscores), and it is listed as NAME: {} in the apps: block of profile.yml; .gitignore gains /apps/*/panel/vendor/ when it lacks it. No port is pinned. A name whose package would be a Python keyword or shadow a standard-library or OSPREY module is refused, and whatever exists at apps/NAME/ unless --force replaces it.

osprey app check [--repo DIRECTORY]

Run what osprey build checks of the applications the apps: block of profile.yml names, then the import boundary over each of their Python packages, that panel/index.html loads the design-system tokens.css, base.css and primitives.css and every class the panel sets has a CSS rule, ESLint over panel/ when it holds JS, and Vitest over tests/**/*.test.{js,mjs} when that matches a file. Prints every violation with its application, field and rule, and exits 1. An apps/<name>/ the block does not name is reported and not checked. An application an installed package ships is checked too; its violations name the distribution (<dist>:<module path>/<file>). The JS checks execute the application’s JS tests, with none of the shell’s secrets; they need Node and install a pinned toolchain into the user’s cache once; an application with no JS needs neither.

osprey facility#

Check and show the facility description under data/facility/ and import an export into it. See Import a Middle Layer export for the import end to end.

osprey facility validate [--repo DIRECTORY]

Run every check osprey build makes of data/facility/ and render the facility views against the repo’s main profile in a temporary directory. Nothing is written into the repo. A clean tree exits 0, and each model with a kept imported/mml/<model>.response.json prints one response check <model>: … line on stderr, pass or fail; a failing check exits 1 before the render. When the check left rows out of the comparison, a second line for that model follows on stderr, giving the number of rows left out and the count per reason (unwired, no width, unsolved, table calibration); it does not change the verdict or the exit code: response check <model>: left out <n> rows (<k> unwired, <j> no width, <u> unsolved, <t> table calibration). A device whose stated s lies outside its periodic model’s deck is placed modulo the deck’s length, and both osprey build and this command print one facility: place-wrapped: device <id> — …; fix: … warning per device on stderr; the exit code is unchanged. Each link of a knowledge page under data/facility/knowledge that the facility file does not hold, a device_id that is no device id or a facility: link in the body that names no channel or device (or, as facility:place/<id>, no place), prints one facility: link-dangling: page <path> — …; fix: … warning, in osprey build and in this command; the exit code is unchanged. A measurement kind no installed package registers, in a tree that mounts no machine root and lists no application and no dependency, prints one facility: kind-deferred: measurement <model> — …; fix: … warning, in osprey build and in this command; the exit code is unchanged. A group whose sources state different members prints one members-disagree warning naming which source states which member; the group carries them all. Relation claims print, in both commands and with the exit code unchanged, one relation-contested warning per key a dispute leaves unsettled, one relation-coarse per relation type with coarse claims, one alias-shared per scheme name two records carry, one identity-ambiguous per imported layer holding two devices one same_as chain joins, one part-cycle per loop of part_of and runs_on claims, one relation-stub per imported layer with Unidentified devices that claims name, and one place-unplaced per place a relations layer creates top-level with no citation. This command alone then closes stderr with one summary line, relations: <n> claims (<s> stated, <i> inferred); <a> accepted, <c> contested, followed by , <x> superseded when any are; a claim without basis counts as stated, and a file with no claims prints no line. The check converts a monitor reading to position with one slope, taken at the centred beam; that is exact for a straight-line (gain and offset) calibration, and a table-calibrated monitor is left out of the check and counted on the left-out line. If you need a more elaborate BPM calibration in the check, open an issue. A tree that is not clean prints every error of the first failing stage on stderr, one line each and sorted, and the command exits 1. A stale fix’s line carries the block to paste in its place. A settle-tolerance warning the build would print is printed on stderr and does not change the exit code. --repo names the deployment repo; without it, the nearest profile.yml at or above the current directory is used.

osprey facility show [--json] [TEXT] [--repo DIRECTORY]

Build the facility in memory as osprey facility validate does, and exit 1 like it, with its lines on stderr, when the build stops. Without TEXT it prints the identity, the record count per kind (places, devices, channels, groups), the relation claim count and the wiring record count per model, each model with its engine, whether the main render serves it and its solve setting, and each view with its path under the render and whether it is written. The views are those of the main render, build/config.yml; a login’s selection does not change them. A view that is not written names the config key or model fact that left it out. With TEXT it prints every place, device, channel, group or model of that id; when there is none, the relation claim of that id; when there is none, the places and devices TEXT names by a names or scheme_names name, or, for a place, by the last segment of its id (S01 finds SR/S01, never SR/XS01). Each record prints under its kind with its provenance (the layer and file each field came from, the fields the build filled) and the fixes applied to it; a header <kind> <id> (match: <match>) marks a record TEXT did not name by id. A place or device lists the claims it is an end of, one line each: id, the claim read subject first with the record itself written (this) (type <other> when the record is the subject, <other> type (this) when it is the object, (this) type (this) when it is both), standing, and the unit when the claim’s place end gives one. A TEXT that matches nothing prints facility show: no record <text> on stderr and exits 1. --json prints one JSON document on stdout and every other line, view notes included, on stderr; on an error stdout is empty. The facility document’s keys are identity, counts (places, devices, channels, groups, relations, and wiring keyed by model), models (name, engine, served, solve) and views (name, path, written, and reason only on a view that is not written); the record document is records, one entry per record with record, kind, match (id, claim, name or segment), provenance and fixes_applied, and claims on a place or device (id, type, other, standing, role — subject, object or both, other then being the record itself — and unit when given), in place, device, channel, group, model order.

osprey facility import

Group for the importers that write an export as sources under data/facility/imported/; the importers are mml, list and relations.

osprey facility import mml EXPORT... [--repo DIRECTORY]

Write MML exports as the mml layer’s sources under data/facility/imported/mml/ and seed each authored file that does not exist yet. EXPORT is an export’s <stem>.ao.json; give every export the mapping names. Each export’s deck is held to the lattice fingerprint the export states: a deck with another element count, family-name digest or parameter-element indices prints import mml: export-invalid: <system>: the deck <file> holds <fact> <value> and the export states <value>; import the lattice the export was sampled from, or export again over this one, writes nothing and exits 1. An energy that differs alone prints the same sentence after import mml: deck energy: and the import goes on, and an export that states no fingerprint prints one import mml: deck unchecked: line. The mapping is then checked against the exports: a problem prints one <key>: <message> line per problem, then <n> problems in data/facility/imported/mml/mapping.yaml; fix each and check again. (1 problem for one), writes nothing and exits 1. A system the mapping names and no given export carries is one such line, models.<system>: <system> is no exported system. A mapping with the wrong structure, or a profile that does not resolve, prints a one-line failure with its cause and exits 1. Before it reads an export, the import runs one step that every format runs. Hand-written records of a kind the format writes print import mml: data/facility/ holds hand-written <kinds> records, which this import writes:, each file, and a remedy, then exit 1 with nothing changed. A facility that already holds an imported layer is not refused: records written by hand beside a layer stay. Otherwise bundled files are replaced, printing import mml: replaced the bundled <name> facility (<n> files), everything else stays, the knowledge indexes are regenerated, and a blank knowledge/index.md is left when no page remains. The mml format writes channel, device, group, model, deck, seed, limit, identity and measurement records.

osprey facility import mml --print-exporter

Print the MATLAB exporter the mml layer ships. Needs neither a repo nor an export.

osprey facility import list FILE [--repo DIRECTORY]

Write a CSV channel list as the list layer’s sources, data/facility/imported/list/channels.yaml, one channel record per row. It runs the same step as the mml import under the prefix import list:, refuses only hand-written channel and device records, and seeds the knowledge stub. FILE is UTF-8 CSV whose header row names address, required, and any of the optional columns role (empty means readback), pair, device, place, unit, description, tags (;-separated), s (metres, a number) and model (the model whose deck s is measured in), in any order. A file whose first row names no address column holds one address per line. s and model are the position of the row’s device: for each device a row states s for, the import writes {id, s}, plus model when stated, to data/facility/imported/list/devices.yaml, and no other device field, so the device merges with one another source declares, or is created holding only its position. osprey build places it by the span of its model containing s. A row that names both a device and a place, states a role other than setpoint, readback or none, has no address or repeats one, states s or model with no device, or states an s that is not a finite number, a row with more cells than the header, two rows stating different s or model for one device, and an unknown or repeated column each print one facility: source-invalid: line; the import writes nothing and exits 1. A model for a device no row states s for is ignored with one import list: warning on stderr naming the file, row, device and model; the rest of the device’s rows are imported.

osprey facility import relations TABLE --layer NAME [--names FILE] [--places FILE] [--members FILE] [--stub-unknown] [--repo DIRECTORY]

Write relation tables as the sources of the layer NAME under data/facility/imported/<NAME>/. TABLE holds the claims; --names, --places and --members name the three optional tables the claims lean on. The tables and their columns are in Relation tables. A device end the facility lacks is stubbed only when its row states subject_class or object_class, or, as Unidentified, with --stub-unknown; place and group ends are never stubbed. Ends and names resolve against the whole facility except the layer being replaced. The layer directory is replaced whole and no other file changes: the run does not replace a bundled facility nor refuse hand-written records. Each file written prints one wrote <path> line. NAME must match [a-z0-9][a-z0-9_-]* and is not authored, list or mml, and a directory holding a file this import never writes is refused. A refused name, directory or row prints one facility: source-invalid: line per problem; the import writes nothing and exits 1. A profile that does not resolve prints a one-line failure and exits 1. A profile that states machine: imports into that machine root.

osprey sim#

List, inspect and apply the scenarios of a simulated deployment. The scenarios are authored under data/facility/scenarios/ and served from the simulator view the build writes under build/data/simulator/; a repo with no build, or a build with no simulator view, exits 1 with run 'osprey build' first. osprey sim alone prints its help, naming the three verbs. All three verbs take --repo DIRECTORY; without it, the nearest profile.yml at or above the current directory is used.

osprey sim list [--repo DIRECTORY]

Print one line per scenario of the view, sorted by name: <marker> <name>  (logbook: yes|no), where the marker is * for a scenario in the active set and a space otherwise, and logbook says whether the scenario narrates logbook entries. The scenario’s description follows on its own indented line when it has one. nominal is always in the active set.

osprey sim status [--target <live|va|standin>] [--repo DIRECTORY]

Print one <model>: <status> line per served physics model, sorted by name, where the status is ok, no deck for a model that names no deck and wires no channel (it is not built, by design, and its channels are the texture’s), or FAILED: followed by the model’s error text. The command exits 1 when any model failed, after printing every line. One log: <absolute path> line per model follows, naming the log the simulator appends to under var/simulator/, each followed by any scenario-overlap records from that log. --target selects the control target to report on and defaults to the deployment’s own; a target the deployment does not configure exits 1. With the simulator served in process the status comes from the composite this process holds; on any other target it is read from the model’s status channel, <code>:SIM:<model>:STATUS, through that target’s connector.

osprey sim apply NAMES... [--no-seed] [--no-seed-logbook] [--no-seed-archiver] [--yes] [--now ISO8601] [--repo DIRECTORY]

Make NAMES the active scenario set, with nominal always included, and seed their stored data: the ARIEL logbook is purged and reseeded from the set’s logbook entries, and the affected windows of the stored archive are rewritten from the set’s archiver events. The set is judged on the simulator view before anything is written: two scenarios that write one target are refused, naming that target, and the command exits 1. --no-seed-logbook leaves the logbook untouched, --no-seed-archiver the stored archive, and --no-seed both. --yes (-y) skips the confirmation prompts before the purge and the archive rewrite. --now freezes the apply-time anchor to an ISO-8601 instant so seeded logbook dates are reproducible; a naive value takes the facility timezone, and the OSPREY_SIM_NOW environment variable is read when the option is absent. It never adds or removes the scenario sessions a first deploy laid down.

osprey sim list
osprey sim apply rf-thermal demo-history
osprey sim status

osprey ariel#

Manage the ARIEL logbook search service. Run from anywhere inside a deployment repo: the commands read its build/config.yml.

Every command gives the database 30 s to answer when it opens it; the limit covers the open, not the work after it. A database that does not answer ends the command with exit code 1 and the ARIEL store at <host>:<port>/<database> did not answer within 30 s. A database that refuses the connection fails at once.

osprey ariel quickstart [-s, --source PATH]

Full setup: migrate, then ingest --source or the configured ingestion source; with neither, enhance what the logbook already holds (a deploy seeds it from the active scenarios).

osprey ariel status [--json]

Show the database connection, embedding tables and enhancement counts. Includes the vocabulary line (with the e1:… vocabulary key when entries are expanded) and, per text-embedding table, one line for each group of vectors built with other settings than the running ones, ending with the reembed command that rebuilds them.

osprey ariel migrate

Create or update the database tables the enabled modules need.

osprey ariel sync [--limit N] [--watch]

Idempotent migrate + incremental ingest + enhance. Safe to run on every build; on a fresh database, runs a full ingest. --watch keeps polling the source after the sync.

osprey ariel ingest -s, --source PATH [-a, --adapter TYPE] [--since DATE] [--limit N] [--dry-run]

Ingest logbook entries from file or URL.

osprey ariel watch [-s, --source PATH] [-a, --adapter TYPE] [--once] [--interval N] [--dry-run]

Poll the source for new entries and ingest them. --once runs a single poll cycle. Nothing is ingested until one earlier ingest has run, unless ingestion.watch.require_initial_ingest is false.

osprey ariel enhance [-m, --module NAME] [--force] [--limit N] [--retry-failed] [--refresh-stale] [--entry ID]

Run the enhancement modules over entries not yet enhanced. --force re-runs the text modules; --retry-failed retries what --module gave up on. --refresh-stale, with --module image_caption, captions again the pictures captioned with an older prompt. --entry ID, with --module, re-runs that module for one failed or stale entry; it is the command an entry’s enhancement card shows, and it takes no option besides --module.

osprey ariel qmd-resync [--rebuild]

Re-export entries the qmd markdown mirror never saw — entries created in the web interface, attachment uploads, and entries written through the logbook write service. --rebuild wipes the mirror and re-exports everything, which is what to run after purge. ingest and watch already do this pass on their own. Prints the vocabulary key it used as its last row (Expansion key).

osprey ariel models

List the embedding models and their tables.

osprey ariel search QUERY [--mode keyword|semantic|hybrid] [--limit N] [--json]

Execute a search query. Without --mode, the deployment’s ariel.default_search_mode decides.

osprey ariel vocab-check [PATH] [--json]

Validate a facility vocabulary file — the shorthand-to-prose mapping that query expansion uses. Checks PATH, or the file named by ariel.vocabulary.path when no path is given. Needs no database. Exits 1 and lists every error when the file is broken; warnings never fail it.

osprey ariel reembed --model NAME --dimension N [--batch-size N] [--dry-run] [--force]

Re-embed entries with a different model, or with the current vocabulary settings after status reports stale vectors (--force). --dry-run prints the plan, including Running key: r1 or Running key: r1:e1:<hex> — the key each new vector will record. reembed refuses to start when ariel.vocabulary.expand_entries is on but the vocabulary does not load; that refusal names the loader error and the remedy fix ariel.vocabulary.path or set ariel.vocabulary.expand_entries: false. sync, ingest, watch, enhance, quickstart and qmd-resync refuse the same way. Without --dry-run it also refuses when the table predates the key column (schema behind code: run osprey ariel migrate).

osprey ariel purge [-y, --yes] [--embeddings-only]

Delete all ARIEL data. --embeddings-only keeps the entries and clears the embedding tables.

osprey ariel attachments

Group for the attachment copy commands.

osprey ariel attachments backfill [--limit N] [--dry-run] [--probe N] [--wait] [--retry-decoder-failed]

Record and copy the pictures of every stored entry, newest first, and render stored originals that have no rendition. --dry-run counts what would be fetched; --probe N also requests N sampled pictures and prints an estimate. --wait waits for a copy running in another process. --retry-decoder-failed renders again the pictures the decoder could not read.

osprey ariel quickstart
osprey ariel search "RF cavity fault"
osprey ariel vocab-check data/facility/ariel/vocabulary.yml

osprey web#

Launch the Web Terminal interface. See Run the Web Terminal.

osprey web [OPTIONS]

Start the web terminal server (default: 127.0.0.1 at the port layout’s web port, port_base + 100, so 10100 on the default block). On startup it prints a login URL (…/?token=…) that signs you in and then redirects to the clean address. The cookie it sets lasts modules.web_terminals.auth.session_lifetime seconds (default 43200, 12 hours) and survives a browser restart; signed-in sessions are kept on disk, so restarting the server on the same port leaves them signed in. The URL is printed once, but its token is the server’s own secret and stays valid for the life of the process — treat it like a password.

-p, --port INTEGER — Port (default: OSPREY_WEB_PORT, then config, else the port layout’s web port, port_base + 100). 0 lets the system choose; the startup line names the port; not with --reload.

--host TEXT — Host to bind to (default: from config, else 127.0.0.1).

--shell TEXT — Shell command to run (default: claude).

--repo DIRECTORY — Deployment repo to act on (default: nearest profile.yml at or above cwd).

--detach — Run in background (PID written to var/osprey-web.pid). The login token is held only in memory; if the printed URL is lost, stop and restart the server to mint a new one.

--reload — Auto-reload for development.

--skip-preflight — Skip the pre-flight checks (companion port collisions and the like) and start anyway. Without it, a failed check refuses the start.

osprey web stop [--repo DIRECTORY]

Stop a background web terminal server.

osprey web sessions

Group for the commands that manage the sessions kept on disk.

osprey web sessions clear [--repo DIRECTORY] [--force]

Forget the sessions this project has kept on disk, so everyone has to open the login URL again. It refuses to run while a server is using them — stop it first with osprey web stop.

--force — Delete them even so. Browsers already signed in to the running server keep working until that server exits.

This is not the multi-user terminal’s Logout button: there, Logout ends one person’s session in a running server, while sessions clear empties the stored sessions of a stopped one.

osprey web
osprey web --port 9000 --host 0.0.0.0
osprey web --detach
osprey web stop
osprey web sessions clear

osprey theme-lab#

Design a theme in the browser. Starts a local server for OSPREY’s design system and opens the Theme Lab, where you pick an accent color and see it previewed live on dark and light mock-ups of the web terminal, with contrast badges that update as you go. Copying the export block gives you a ready-to-paste description of the theme to request; the lab itself does not write theme files. See Theming.

osprey theme-lab [OPTIONS]

Serve the Theme Lab and open it. The URL is printed as well, so the page can be opened by hand if no browser appears. It is a login URL at the server root (…/?token=…): opening it sets a session cookie and then redirects to the lab itself.

-p, --port INTEGER — Port to serve on (default: an unused port chosen automatically).

--no-browser — Do not open a browser window; print the URL only.

osprey theme-lab
osprey theme-lab --port 9000
osprey theme-lab --no-browser

osprey audit#

Audit a build profile or project directory for safety risks. Uses an AI reviewer to analyze permissions, hooks, MCP server configs, convention directories, and lifecycle scripts.

osprey audit TARGET [OPTIONS]

The reviewer runs on the deployment’s configured provider (claude_code.provider), so an audit needs a built project: point it at one, or pass --build to build the profile first.

--build — Build a profile in a temp directory, then audit the result.

--model TEXT — Model for the reviewer agent. Defaults to the project’s main model.

--budget FLOAT — Maximum budget in USD.

-v, --verbose — Show verbose output.

--json — Output as JSON.

osprey audit my-project/
osprey audit profile.yml --build
osprey audit project/ --json

osprey scaffold#

Emit the repository’s CI files and boot unit, and manage build artifact ownership. Framework-managed build artifacts (agents, rules, etc.) can be claimed per-facility for in-place editing. A claim moves the artifact out of the build zone and into the profile beside it; the next build copies it back and registers it as user-owned, so a rebuild leaves your version alone.

All subcommands accept a common flag:

--repo DIRECTORY — Deployment repository to act on (default: the nearest profile.yml at or above the working directory).

osprey scaffold ci [--force]

Emit this repository’s CI pipeline and health check from the profile’s deploy: block: the pipeline at the repository root and the post-deploy health check at scripts/verify.sh. Run it again whenever the block changes. Re-running is safe — a file whose content already matches is left untouched, stamp included, so an OSPREY upgrade alone produces no diff. A file the scaffolder did not write is reported and left alone unless --force is given. ci-extra.yml is never touched: it is yours, and the pipeline includes it. The health check exits 0 unless run with --strict, which exits 1 when a container or a probe is flagged.

osprey scaffold systemd [--force]

Emit the files that start this deployment at boot: a systemd user unit, osprey.service at the repository root, and a boot hook, scripts/osprey-boot-hook.sh, plus the commands to install the unit. The unit runs osprey up -d from this repository and osprey down on stop, with both the repository and the osprey program written in as full paths — systemd starts a unit with no working directory and a short PATH. Run it on the machine that will run the deployment, and again after the repository moves or OSPREY is reinstalled elsewhere. Re-running is safe on the same terms as ci: a matching file is left untouched, and a file the scaffolder did not write needs --force. Refuses when no osprey program can be found to name. Starting at boot also needs loginctl enable-linger $USER once — see Deploy a Facility. When $HOME is on an NFS or autofs mount it also warns that linger alone will not survive a reboot there, prints the root-only user@<uid>.service drop-in that orders the user manager after a systemd-managed mount, and shows the two crontab lines that run the boot hook at boot — the route for a daemon-managed autofs home, and the no-root fallback elsewhere.

osprey scaffold tiers [--from PRESET] [--force]

Write tiers/<name>.yml for every tier the preset’s web-terminal roster names, as osprey init does. A file that already matches is left untouched; one that differs is reported and left alone unless --force is given. --from names the preset (default: the preset this repo was created from).

osprey scaffold pull PRESET[:PATH] [--list] [--force] [--with-content] [--repo DIRECTORY]

Copy a preset’s packaged content into this repo, each file at the same path, for you to edit and commit: demo copies the whole app template, demo:data/facility/knowledge one subtree of it. --list prints every path the preset offers and copies nothing. The knowledge base arrives as its index.md files alone, rebuilt from what landed; --with-content brings its documents too. A file that is already here stops the pull before anything is written unless --force is given; a symlink on the way to a target is always refused.

osprey scaffold list

List all build artifacts and their ownership status (framework vs. user-owned).

osprey scaffold claim NAME

Move an artifact out of build/ and into the repository’s profile, into the convention directory for its kind (rules/safety.md, skills/orbit-check/, services/postgresql/, hooks/my-guard). A file moves as a file; skills and services move as whole directories. The build copy is moved, not copied — it lives in one place until the next osprey build renders it again.

Refused, with the reason: a generated artifact rather than an authored one — CLAUDE.md, .claude/settings.json, .mcp.json, hook_config.json — where the message names the config key that does control it; and a profile slot that is already occupied. See Taking ownership of a framework artifact.

osprey scaffold diff NAME

Show a unified diff between the current framework template (re-rendered) and your file at the canonical output path. For a claimed service directory, diffs every file in the directory against the packaged template.

osprey scaffold unclaim NAME

Release ownership and restore framework management. The next build overwrites the file with the framework template. Ownership a build derived from the profile is re-registered by the next build, so this holds only until then — give the artifact up for good by deleting it from the profile’s convention directory.

osprey scaffold web-terminals

Group for the two verbs that check and render the deployment’s modules.web_terminals stanza.

osprey scaffold web-terminals lint [--repo DIRECTORY]

Validate the deployment’s modules.web_terminals stanza (port-family allocation, reserved service names, duplicate users, login references). Exits non-zero on error-severity findings; warnings do not fail the check, so it is safe to wire into a CI gate. The retired --config is refused, as under render below.

osprey scaffold web-terminals render [--repo DIRECTORY] -o DIRECTORY

Render the multi-user deployment artifacts (docker-compose overlay, nginx routing fragment, static landing page) into -o/--output. Lints first by default and aborts on errors; --no-lint skips the pre-check.

Both verbs read the stanza from the repository’s built config.yml. --config is retired: it is still accepted so that an old command line gets an error naming what replaced it (--repo and the built config.yml), and the verb exits 1 without doing anything.

osprey scaffold ci                             # Re-emit the CI files
osprey scaffold systemd                        # Write the boot unit
osprey scaffold tiers                          # Write the tier files
osprey scaffold pull demo --list               # Show what a preset offers
osprey scaffold list                           # Show all artifacts
osprey scaffold claim agents/channel-finder    # Claim for editing
osprey scaffold claim services/postgresql      # Freeze a service template
osprey scaffold diff agents/channel-finder     # Compare yours vs framework
osprey scaffold unclaim rules/safety           # Restore framework management
osprey scaffold web-terminals lint             # lint this project's stanza
osprey scaffold web-terminals render -o deploy/

osprey vendor#

Manage locally bundled vendor assets (JS/CSS/fonts) for firewalled deployments. By default OSPREY interfaces load third-party libraries directly from CDN; set OSPREY_OFFLINE=1 (or offline: true in config.yml) to switch the interfaces over to local bundles.

osprey vendor fetch [OPTIONS]

Download all vendor assets declared in the manifest into static/vendor/. Run once on firewalled deployments before starting osprey web with OSPREY_OFFLINE=1. In default CDN mode this command is optional.

-q, --quiet — Suppress per-file output.

-t, --target DIR — Fetch only the assets for this manifest target directory, e.g. tuning/static/vendor/ (repeatable). Default: every target. A target the manifest marks "base": "package" is named relative to the osprey package rather than its interfaces package; an unknown target is refused with the list of known ones. An application’s own vendor: entries are fetched by osprey build, not by this command.

Behind a proxy that re-signs TLS with a site CA (e.g. Squid), the fetch fails cert verification until it is pointed at the site’s CA bundle. That is the first remedy to reach for — verification stays on:

OSPREY_CA_BUNDLE=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem \
  osprey vendor fetch

SSL_CERT_FILE works too (Python’s default SSL context honors it); OSPREY_CA_BUNDLE wins when both are set. The path above is the RHEL-family system bundle — on Debian-family hosts it is /etc/ssl/certs/ca-certificates.crt.

-k, --insecure — The fallback when no CA bundle is at hand: skip TLS cert verification. Every asset is still checked against its manifest SHA256, so this is safe behind corporate proxies that intercept TLS. Also enabled via OSPREY_VENDOR_INSECURE=1.

osprey vendor verify

Verify all vendor assets exist on disk with correct SHA256 checksums.

osprey vendor fetch                    # Download all assets
OSPREY_CA_BUNDLE=/path/to/ca.pem osprey vendor fetch   # TLS-intercepting proxy, verified
osprey vendor fetch --insecure         # Fallback: no CA bundle at hand
osprey vendor verify                   # Check checksums

Environment Variables#

The variables the CLI reads, and where they belong, are listed in Environment Variables.