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#
--versionShow framework version and exit.
-v, --verboseShow debug output, including every container command run. The transcript takes the place of the progress report rather than joining it, so under
-vno 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.--helpShow 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 |
|---|---|
|
No fallback exists and none may be invented. A deployment’s
|
|
Computed when the key is read. The comment above the key names what it is computed from. |
|
The reader supplies none: it raises, or nothing reads the key yet, or “unstated” is deliberately not “false”. The comment says which. |
|
The leaf has no reader of its own, so |
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 TARGETCheck a profile without building anything.
TARGETis a directory holding aprofile.ymlor a path to a profile file. Resolvesextends:chains and reports every problem found — convention directories, thedata:tree, service templates, lifecycle steps, env vars. Exits 0 when valid, 2 with the accumulated errors when not. Inside a deployment repository, plainosprey validatechecks that repository without naming a target.osprey profile presetsList bundled preset names, one per line. Every name printed is usable as
--preset NAMEforosprey init.osprey profile artifactsList 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 initprints, 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 readsprofile.ymland the login files beside it; nothing is built, started or probed.--jsonprints 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, withvar/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
.envthat 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 |
|---|---|---|
|
Retire one person: remove their web-terminal workspace. |
|
|
Remove workspaces for people no longer on the roster. |
|
|
(Re)seed workspaces from the roster; |
— |
|
Change one user’s login password (password authentication only). Prompts without echoing, and ends that user’s sessions. |
— |
|
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. |
|
|
Print the URL that opens that user’s terminal under |
— |
|
Render |
|
--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 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 |
|---|---|---|
|
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. |
— |
|
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 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.
--pipelinenames the paradigm: the file is read as that paradigm, and without--databaseit is the one atchannel_finder.pipelines.<pipeline>.database.path— the command refuses, naming that key, when it is unset. Without--pipelinethe 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.
--depthis the tree depth to display and--max-itemsthe most items shown per level (both default3;-1for unlimited).--sectionsis a comma-separated list oftree,stats,breakdown,samplesorall(defaulttree).--focusshows one path only (M:QBfor the QB family in the M system).--databasereads that file instead of the configured one, and--fullshows 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.mdfiles 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.mdagainst 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.ttlin the deployment repo you stand in or--reponames;--ttlnames another Turtle file. Each stub’sdevice_idis 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 passesosprey app checkas copied. Its names are rewritten toNAME(the Python package toNAMEwith underscores), and it is listed asNAME: {}in theapps:block ofprofile.yml;.gitignoregains/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 atapps/NAME/unless--forcereplaces it.osprey app check [--repo DIRECTORY]Run what
osprey buildchecks of the applications theapps:block ofprofile.ymlnames, then the import boundary over each of their Python packages, thatpanel/index.htmlloads the design-systemtokens.css,base.cssandprimitives.cssand every class the panel sets has a CSS rule, ESLint overpanel/when it holds JS, and Vitest overtests/**/*.test.{js,mjs}when that matches a file. Prints every violation with its application, field and rule, and exits 1. Anapps/<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 buildmakes ofdata/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 keptimported/mml/<model>.response.jsonprints oneresponse 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 statedslies outside its periodic model’s deck is placed modulo the deck’s length, and bothosprey buildand this command print onefacility: place-wrapped: device <id> — …; fix: …warning per device on stderr; the exit code is unchanged. Each link of a knowledge page underdata/facility/knowledgethat the facility file does not hold, adevice_idthat is no device id or afacility:link in the body that names no channel or device (or, asfacility:place/<id>, no place), prints onefacility: link-dangling: page <path> — …; fix: …warning, inosprey buildand 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 onefacility: kind-deferred: measurement <model> — …; fix: …warning, inosprey buildand in this command; the exit code is unchanged. A group whose sources state different members prints onemembers-disagreewarning naming which source states which member; the group carries them all. Relation claims print, in both commands and with the exit code unchanged, onerelation-contestedwarning per key a dispute leaves unsettled, onerelation-coarseper relation type with coarse claims, onealias-sharedper scheme name two records carry, oneidentity-ambiguousper imported layer holding two devices onesame_aschain joins, onepart-cycleper loop ofpart_ofandruns_onclaims, onerelation-stubper imported layer withUnidentifieddevices that claims name, and oneplace-unplacedper 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> supersededwhen any are; a claim withoutbasiscounts 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.--reponames the deployment repo; without it, the nearestprofile.ymlat or above the current directory is used.osprey facility show [--json] [TEXT] [--repo DIRECTORY]Build the facility in memory as
osprey facility validatedoes, and exit 1 like it, with its lines on stderr, when the build stops. WithoutTEXTit 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. WithTEXTit 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 devicesTEXTnames by anamesorscheme_namesname, or, for a place, by the last segment of its id (S01findsSR/S01, neverSR/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 recordTEXTdid 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. ATEXTthat matches nothing printsfacility show: no record <text>on stderr and exits 1.--jsonprints 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 areidentity,counts(places,devices,channels,groups,relations, andwiringkeyed by model),models(name,engine,served,solve) andviews(name,path,written, andreasononly on a view that is not written); the record document isrecords, one entry per record withrecord,kind,match(id,claim,nameorsegment),provenanceandfixes_applied, andclaimson a place or device (id,type,other,standing,role—subject,objectorboth,otherthen being the record itself — andunitwhen given), in place, device, channel, group, model order.osprey facility importGroup for the importers that write an export as sources under
data/facility/imported/; the importers aremml,listandrelations.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.EXPORTis 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 printsimport 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 afterimport mml: deck energy:and the import goes on, and an export that states no fingerprint prints oneimport 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 problemfor 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 printimport 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, printingimport mml: replaced the bundled <name> facility (<n> files), everything else stays, the knowledge indexes are regenerated, and a blankknowledge/index.mdis 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-exporterPrint 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 prefiximport list:, refuses only hand-written channel and device records, and seeds the knowledge stub.FILEis UTF-8 CSV whose header row namesaddress, required, and any of the optional columnsrole(empty means readback),pair,device,place,unit,description,tags(;-separated),s(metres, a number) andmodel(the model whose decksis measured in), in any order. A file whose first row names noaddresscolumn holds one address per line.sandmodelare the position of the row’s device: for each device a row statessfor, the import writes{id, s}, plusmodelwhen stated, todata/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 buildplaces it by the span of its model containings. A row that names both a device and a place, states a role other thansetpoint,readbackornone, has no address or repeats one, statessormodelwith no device, or states ansthat is not a finite number, a row with more cells than the header, two rows stating differentsormodelfor one device, and an unknown or repeated column each print onefacility: source-invalid:line; the import writes nothing and exits 1. Amodelfor a device no row statessfor is ignored with oneimport 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
NAMEunderdata/facility/imported/<NAME>/.TABLEholds the claims;--names,--placesand--membersname 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 statessubject_classorobject_class, or, asUnidentified, 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 onewrote <path>line.NAMEmust match[a-z0-9][a-z0-9_-]*and is notauthored,listormml, and a directory holding a file this import never writes is refused. A refused name, directory or row prints onefacility: 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 statesmachine: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, andlogbooksays whether the scenario narrates logbook entries. The scenario’s description follows on its own indented line when it has one.nominalis 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 isok,no deckfor a model that names no deck and wires no channel (it is not built, by design, and its channels are the texture’s), orFAILED:followed by the model’s error text. The command exits 1 when any model failed, after printing every line. Onelog: <absolute path>line per model follows, naming the log the simulator appends to undervar/simulator/, each followed by any scenario-overlap records from that log.--targetselects 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
NAMESthe active scenario set, withnominalalways 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-logbookleaves the logbook untouched,--no-seed-archiverthe stored archive, and--no-seedboth.--yes(-y) skips the confirmation prompts before the purge and the archive rewrite.--nowfreezes the apply-time anchor to an ISO-8601 instant so seeded logbook dates are reproducible; a naive value takes the facility timezone, and theOSPREY_SIM_NOWenvironment 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
--sourceor 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 thereembedcommand that rebuilds them.osprey ariel migrateCreate 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.
--watchkeeps 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.
--onceruns a single poll cycle. Nothing is ingested until one earlieringesthas run, unlessingestion.watch.require_initial_ingestis 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.
--forcere-runs the text modules;--retry-failedretries what--modulegave 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.
--rebuildwipes the mirror and re-exports everything, which is what to run afterpurge.ingestandwatchalready do this pass on their own. Prints the vocabulary key it used as its last row (Expansion key).osprey ariel modelsList 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’sariel.default_search_modedecides.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 byariel.vocabulary.pathwhen 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
statusreports stale vectors (--force).--dry-runprints the plan, includingRunning key: r1orRunning key: r1:e1:<hex>— the key each new vector will record.reembedrefuses to start whenariel.vocabulary.expand_entriesis on but the vocabulary does not load; that refusal names the loader error and the remedyfix ariel.vocabulary.path or set ariel.vocabulary.expand_entries: false.sync,ingest,watch,enhance,quickstartandqmd-resyncrefuse the same way. Without--dry-runit 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-onlykeeps the entries and clears the embedding tables.osprey ariel attachmentsGroup 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-runcounts what would be fetched;--probe Nalso requests N sampled pictures and prints an estimate.--waitwaits for a copy running in another process.--retry-decoder-failedrenders 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.1at the port layout’s web port,port_base+ 100, so10100on 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 lastsmodules.web_terminals.auth.session_lifetimeseconds (default43200, 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, else127.0.0.1).--shell TEXT— Shell command to run (default:claude).--repo DIRECTORY— Deployment repo to act on (default: nearestprofile.ymlat or above cwd).--detach— Run in background (PID written tovar/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 sessionsGroup 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 clearempties 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 atscripts/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--forceis given.ci-extra.ymlis 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.serviceat the repository root, and a boot hook,scripts/osprey-boot-hook.sh, plus the commands to install the unit. The unit runsosprey up -dfrom this repository andosprey downon stop, with both the repository and theospreyprogram written in as full paths — systemd starts a unit with no working directory and a shortPATH. 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 asci: a matching file is left untouched, and a file the scaffolder did not write needs--force. Refuses when noospreyprogram can be found to name. Starting at boot also needsloginctl enable-linger $USERonce — see Deploy a Facility. When$HOMEis on an NFS or autofs mount it also warns that linger alone will not survive a reboot there, prints the root-onlyuser@<uid>.servicedrop-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>.ymlfor every tier the preset’s web-terminal roster names, asosprey initdoes. A file that already matches is left untouched; one that differs is reported and left alone unless--forceis given.--fromnames 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:
democopies the whole app template,demo:data/facility/knowledgeone subtree of it.--listprints every path the preset offers and copies nothing. The knowledge base arrives as itsindex.mdfiles alone, rebuilt from what landed;--with-contentbrings its documents too. A file that is already here stops the pull before anything is written unless--forceis given; a symlink on the way to a target is always refused.osprey scaffold listList all build artifacts and their ownership status (framework vs. user-owned).
osprey scaffold claim NAMEMove 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 nextosprey buildrenders 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 NAMEShow 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 NAMERelease 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-terminalsGroup for the two verbs that check and render the deployment’s
modules.web_terminalsstanza.osprey scaffold web-terminals lint [--repo DIRECTORY]Validate the deployment’s
modules.web_terminalsstanza (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--configis refused, as underrenderbelow.osprey scaffold web-terminals render [--repo DIRECTORY] -o DIRECTORYRender 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-lintskips the pre-check.Both verbs read the stanza from the repository’s built
config.yml.--configis retired: it is still accepted so that an old command line gets an error naming what replaced it (--repoand the builtconfig.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 startingosprey webwithOSPREY_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 theospreypackage rather than itsinterfacespackage; an unknown target is refused with the list of known ones. An application’s ownvendor:entries are fetched byosprey 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_FILEworks too (Python’s default SSL context honors it);OSPREY_CA_BUNDLEwins 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 viaOSPREY_VENDOR_INSECURE=1.osprey vendor verifyVerify 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.