Command reference

Generated from the argument parser, so it cannot drift from what the commands accept. It lists what each flag is; docs/interfaces.md explains what the commands are for, and is the page to read first.

crane --help and crane <command> --help print the same thing at the terminal.

Global options

Option	What it does
--version	show program’s version number and exit
--database PATH	SQLite file to use. Defaults to $CRANE_DB or ./data/crane.db

Commands

crane init

crane migrate

Option	What it does
--accept-id-scheme	carry on with a database whose identifiers were derived under the old colon-joined recipe, accepting that its existing rows keep them
--dry-run	list what would be applied and stop

crane status

crane lens

crane lens list

Option	What it does
--database DATABASE	—
--json	—

crane import

crane import adapter

Discovers importers installed under crane.adapters.; run with no name to list what this deployment has. Adapters are deliberately absent from published images, because each one describes somebody else's system: a deployment that needs one installs its own. Sources are opened read only, and every source row is accounted for in the reconciliation report.

Option	What it does
--option KEY=VALUE	an adapter specific option, repeatable. Each adapter documents its own
--dry-run	read, resolve, and report, then roll back without writing
--report PATH	write the reconciliation report here
--json	print the report as JSON
--fail-on-unresolved	exit 3 if any source row could not be placed

crane import spec

The contract for supplied data. Read this before writing files. –json gives the machine readable form.

Option	What it does
--json	print as JSON

crane import template

crane import data

Loads a directory of CSVs, a single CSV, or a JSON bundle. Only the datasets present are touched. Validation runs over the whole batch before anything is written, so the result is a clean load or a clean failure. Exit code 4 means the input did not validate.

Option	What it does
--dry-run	validate and report, write nothing
--json	print the report as JSON

crane import csv

Loads a directory of CSVs, a single CSV, or a JSON bundle. Only the datasets present are touched. Validation runs over the whole batch before anything is written, so the result is a clean load or a clean failure. Exit code 4 means the input did not validate.

Option	What it does
--dry-run	validate and report, write nothing
--json	print the report as JSON

crane import json

Loads a directory of CSVs, a single CSV, or a JSON bundle. Only the datasets present are touched. Validation runs over the whole batch before anything is written, so the result is a clean load or a clean failure. Exit code 4 means the input did not validate.

Option	What it does
--dry-run	validate and report, write nothing
--json	print the report as JSON

crane import sbom

The wizard’s loop from a shell, calling the same function: identify SPDX or CycloneDX by content, store by hash so a re-registration is recognised, attach to a product, turn the packages into components with dependency depth unless –no-components, and queue validation with a rescore behind it. Exit 4 if any document was refused.

Option	What it does
--subject REF	where to attach: a product slug, or component:SLUG, workflow:SLUG, repo:LOCATOR for an SBOM produced at that level. Defaults to what each document says about itself, as a product
--no-create	refuse documents for products that do not exist instead of creating them
--no-validate	register only; queue no validation and no rescore
--no-components	register a product-level document as evidence of the product without turning its packages into components. For a portfolio whose component model is curated and an SBOM’s package list would bury it
--requested-by REQUESTED_BY	who asked, recorded on the queued jobs
--json	—

crane export

Writes the migration bundle: every dataset as one JSON object, importable into an empty database to reproduce the portfolio, including scope decisions, exceptions, identity mappings and review states. Evidence is named by uri and hash rather than embedded. Deliberately not carried: finding states, decision records beyond scope and exceptions, settled conflicts, and job or score history – the bundle is the portfolio, not the ledger, and the database file itself is the full dump. The same bundle is GET /api/v1/export.

Option	What it does
--out PATH	write here instead of stdout
--history	include relationships that have ended, with the date they ended. The default bundle is the portfolio as it is now, so an ended relationship is simply absent; with this it is present and dated, and a question about a past month is answerable from the bundle rather than only from the database file

crane collect

crane collect github

Reads what the repositories already publish – workflows, runs, releases, SBOM assets, CODEOWNERS, packages – and imports it as observed, never approved. Repositories become source assets, not products: attaching them to products is a decision this tool records, not one a scanner makes. The worker reads CRANE_GITHUB_TOKEN from its environment; without it, public organizations scan inside GitHub’s anonymous rate limit. The same operation is POST /api/v1/collect/github.

Option	What it does
--dry-run	scan one batch and report what it would create, writing nothing
--full	re-read everything, ignoring the last completed scan’s watermark. Needed periodically: an incremental scan reads what changed, so it never notices something that was deleted
--check	read one object and report what came back, then stop. Verifies the credential and the connection without queueing a scan or writing anything
--json	—

crane collect gitlab

Reads what the projects already publish – the pipeline configuration and its latest run, releases, SBOM release assets, CODEOWNERS – and imports it as observed, never approved. Projects become source assets, not products: attaching them to products is a decision this tool records, not one a scanner makes. A project holds one pipeline configuration rather than many workflow files, so it contributes at most one build workflow. An archived project is a retired pipeline rather than an absent one. The worker reads CRANE_GITLAB_TOKEN from its environment; without it, public projects scan inside GitLab’s unauthenticated rate limit. The same operation is POST /api/v1/collect/gitlab.

Option	What it does
--dry-run	scan one batch and report what it would create, writing nothing
--full	re-read everything, ignoring the last completed scan’s watermark. Needed periodically: an incremental scan reads what changed, so it never notices something that was deleted
--check	read one object and report what came back, then stop. Verifies the credential and the connection without queueing a scan or writing anything
--json	—

crane collect ado

Reads what a project’s repositories and pipelines already publish and imports it as observed, never approved. Give an organization, or ‘organization/project’ to scan one project. A pipeline costs an extra call: the listing does not name the repository it builds, only the per-pipeline detail does, and without it every Azure repository would be unattached. A pipeline building a repository outside Azure – a GitHub one, commonly – has that recorded by locator rather than resolved to an Azure repository that does not exist. The worker reads CRANE_ADO_TOKEN from its environment. The same operation is POST /api/v1/collect/ado.

Option	What it does
--dry-run	scan one batch and report what it would create, writing nothing
--full	re-read everything, ignoring the last completed scan’s watermark. Needed periodically: an incremental scan reads what changed, so it never notices something that was deleted
--check	read one object and report what came back, then stop. Verifies the credential and the connection without queueing a scan or writing anything
--json	—

crane resolve

crane resolve sources

One job per distinct purl, idempotent on the purl forever. Needs the purl2src executable on the worker; set CRANE_PURL2SRC_BIN when it lives in a virtualenv. The same operation is POST /api/v1/resolve/sources.

Option	What it does
--subject SUBJECT	limit to one component slug
--database DATABASE	—
--json	—

crane measure

crane measure health

Idempotent per purl per month, because health goes stale. A host the tool cannot speak ends unmeasured, never failed. Needs the suphm executable on the worker (CRANE_SUPHM_BIN); suphm is AGPL-3.0 and runs at arm’s length as a separate process, never bundled. The same operation is POST /api/v1/measure/health.

Option	What it does
--subject SUBJECT	limit to one component slug
--database DATABASE	—
--json	—

crane interpret

crane interpret run

A stored prompt and the exact input text, read by an agent CLI in its non-interactive mode on whichever machine runs this definition – a runner by default, this server where the definition has been set back to local. Queued either way; this does not run it. Never a verdict: the answer lands as an AGENT-REVIEW finding. The same operation is POST /api/v1/interpret.

Option	What it does
--input INPUT	file holding the text to read; stdin otherwise
--database DATABASE	—
--json	—

crane validate

crane validate sbom

Queues one job per SBOM artifact per profile and returns immediately. A worker executes them. With no –profile, validates against every profile an active obligation policy asks for.

Option	What it does
--profile PROFILE	ossbomer profile id, repeatable. Defaults to what the policies require
--subject SUBJECT	limit to one product or component slug
--requested-by REQUESTED_BY	who asked, recorded on the job
--json	—

crane validate profiles

Option	What it does
--json	—

crane assess

Evaluates every check in an obligation policy and stores the score with the per check explanation behind it. Nothing is approved by scoring.

Option	What it does
--subject SUBJECT	score one product by slug
--detail	print every check for every product
--dry-run	compute without storing
--queue	queue the rescore as a job for a worker instead of scoring here. What POST /api/v1/assess does, and the shape to use next to a running server
--json	—

crane demo

Eight invented products chosen to show the situations this exists for: a shared component, one with no build, SBOMs that pass and fail, a document that cannot be read, and a product nobody has scoped.

Option	What it does
--force	seed even if data is present
--json	—

crane policy

crane policy list

Option	What it does
--json	—

crane policy set-rollup

Cut a new version of an obligation that counts the relationship types you name. A new version rather than an edit, because the version and its hash are how a score from before is told from a score from after – so numbers already reported keep citing the rules they were computed under.

Option	What it does
--edge product_component | product_relationship	product_component is what the product is made of; product_relationship is what a parent product ships
--types TYPES	comma separated relationship types, or ‘’ for none at all
--unset	say nothing about this edge, which is not the same as saying none
--check CHECK	configure one check rather than the whole obligation
--database DATABASE	—
--json	—

crane job

crane job list

Option	What it does
--status STATUS	pending, running, succeeded, failed, cancelled
--limit LIMIT	—
--json	—

crane job prune

Deletes the working copy and the logs of finished runs, keeping failures longer than successes because those are the ones somebody opens. Then the ledger rows for runs nothing still points at, and the stored objects nothing claims, and a VACUUM so the file actually shrinks. A run id that is provenance for a claim, an evidence artefact or a state change is kept however old it is. Safe to run on a schedule.

Option	What it does
--dry-run	list what would go and remove nothing
--database DATABASE	—
--json	—

crane job show

Option	What it does
--json	—

crane job cancel

crane job retry

Only for jobs that ended badly. The old run stays as the record of the failure. The same operation is POST /api/v1/jobs/{id}/retry.

Option	What it does
--database DATABASE	—
--json	—

crane worker

Runs queued jobs. The –once form drains the queue and exits, which is what belongs in cron.

crane worker run

Option	What it does
--once	drain the queue and exit. The default, and the shape to put in cron
--follow	keep polling instead of exiting when the queue is empty
--max-jobs MAX_JOBS	stop after this many jobs
--poll-seconds POLL_SECONDS	—
--quiet	—
--json	—
--only DEFINITION	claim only these job definitions, repeatable. The shape for a worker on a machine that has one tool installed and not the others. For a tool on a machine that should not hold the database at all, use a runner instead
--skip DEFINITION	claim everything except these, repeatable. Leaves those jobs pending for a worker that has the tool, rather than failing them here

crane scope

crane scope list

Option	What it does
--json	—

crane scope set

A governed act, not a field update. It writes an approved decision carrying who decided and why, and only then a claim citing it. An import that disagrees is not deleted; it is kept as a conflict.

Option	What it does
--rationale RATIONALE	why. Required, and at least eight characters: this is the sentence somebody reads in a year
--by BY	who decided. Required: an approved decision with no name against it is not one. Matched against known parties, and recorded either way, as a name rather than a verified identity
--database DATABASE	—
--json	—

crane scope rule

One judgement covering many subjects. A scope decision is per subject on purpose – it carries a rationale and an authority, and one sentence pasted across twenty of them is twenty assertions nobody made – and that does not scale to thousands. A rule changes what the decision is about: the rationale is true of the rule, so it is true of everything the rule matches, however many that is. It is re-evaluated rather than stamped, so a subject that stops matching stops being covered.

crane scope rule new

Option	What it does
--org-unit ORG_UNIT	division, organization or team name, or ‘team:Edge Team’ to disambiguate
--source-system SOURCE_SYSTEM	the system subjects came from
--lifecycle LIFECYCLE	—
--no-build	components with no build workflow at all
--origin third_party | internal | unclassified	—
--rationale RATIONALE	why, and it has to be true of everything the rule matches
--by BY	who decided
--expires-on EXPIRES_ON	ISO date. Omitted means permanent, which is worth asking for
--apply	apply it now rather than leaving it to the next run
--database DATABASE	—
--json	—

crane scope rule list

Option	What it does
--database DATABASE	—
--json	—

crane scope rule apply

Option	What it does
--database DATABASE	—
--json	—

crane scope rule retract

Option	What it does
--reason REASON	—
--database DATABASE	—
--json	—

crane assessor

An assessor runs where it likes and submits check results over the API. Registering one and issuing its credential are decisions carrying a name; everything after that happens over HTTP. See ADR 0003.

crane assessor register

Registers the namespace its check keys sit under. An interpretive assessor is one whose results are a model’s reading: those may only be review_needed or source_inaccessible, and a person confirming is what turns one into anything else.

Option	What it does
--kind tool | interpretive	—
--description DESCRIPTION	—
--by BY	who decided to accept results from it
--database DATABASE	—
--json	—

crane assessor list

Option	What it does
--database DATABASE	—
--json	—

crane assessor token

crane assessor token issue

The secret is printed once and stored only as a hash. It carries which source systems’ subjects this token may write about; a token that names none can write about nothing.

Option	What it does
--source-system SOURCE_SYSTEMS	a source system key it may write about. Repeat for several, or pass ‘*’ for every one
--expires EXPIRES_AT	YYYY-MM-DD
--by BY	who issued it
--database DATABASE	—
--json	—

crane assessor token list

Option	What it does
--database DATABASE	—
--json	—

crane assessor token revoke

Submissions presenting it are refused from that moment. What it wrote stays: the results are the assessor’s, not the token’s.

Option	What it does
--by BY	—
--database DATABASE	—
--json	—

crane assessor runs

Option	What it does
--limit LIMIT	—
--database DATABASE	—
--json	—

crane runner

A runner asks the API for work it can execute, runs it, and posts the output back. CRAne never calls the runner, so the machine needs no inbound port and this deployment holds no credential to it. See ADR 0003.

crane runner token

crane runner token issue

It names the job definitions that machine may run. Capabilities the runner declares when it claims narrow that further; they never widen it.

Option	What it does
--definition DEFINITIONS	a job definition key it may claim. Repeat for several, or pass ‘*’ for every externally executed one
--description DESCRIPTION	—
--expires EXPIRES_AT	YYYY-MM-DD
--by BY	who issued it
--database DATABASE	—
--json	—

crane runner token list

Option	What it does
--database DATABASE	—
--json	—

crane runner token revoke

Claims presenting it are refused from that moment. A job it is still holding keeps its lease until that expires and then returns to the queue, because revoking a credential does not stop a program that is already running.

Option	What it does
--by BY	—
--database DATABASE	—
--json	—

crane manage

Everything the web interface can change, from a terminal. The same functions, so the two cannot disagree about what a decision is. Governed acts take a reason and a name; reference data does not.

crane manage create

Option	What it does
--slug SLUG	derived from the name unless given; set it only to match the key a source system already uses
--locator LOCATOR	source assets only, and required for them: the repository, package or image locator, the key an import matches on
--asset-type ASSET_TYPE	source assets only, e.g. repository, package, service
--visibility VISIBILITY	source assets only: internal, public, restricted or unknown
--lifecycle LIFECYCLE	—
--description DESCRIPTION	—
--platform PLATFORM	pipelines only
--environment ENVIRONMENT	pipelines only
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage edit

Option	What it does
--name NAME	—
--lifecycle LIFECYCLE	—
--description DESCRIPTION	—
--platform PLATFORM	—
--environment ENVIRONMENT	—
--asset-type ASSET_TYPE	source assets only
--visibility VISIBILITY	source assets only
--last-run LAST_RUN	—
--last-run-url LAST_RUN_URL	—
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage connect

This product contains that component, this build produces it, this repository is its source. Lands as manual and unreviewed; an import asserting the same edge later lands on the same row. Undrawing is ‘manage review’ with a rejection. The same operation is POST /api/v1/connect.

Option	What it does
--relationship RELATIONSHIP	how they relate; each edge has a default
--note NOTE	—
--create-missing	create a named product or component that does not exist yet, slug derived, then connect it
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage adopt

Creates the component and connects every build workflow whose source is the repository. The scanner deliberately never does this; this is the human half of that bargain. The same operation is POST /api/v1/assets/adopt.

Option	What it does
--slug SLUG	component slug, defaults from the asset’s name
--name NAME	component name, defaults to the asset’s
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage evidence

A governed act, because evidence leaving the pool moves scores. The artifact and its validation history stay; what goes is its standing. The same operation is POST /api/v1/evidence/{id}/state.

Option	What it does
--state stale | superseded | deleted	—
--reason REASON	—
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage evidence-repair

A validation job does not fetch a remote URI, and it used to record that refusal as ‘inaccessible’ – which means it tried and could not see. That is a learned state nothing overwrites, so the mark outlived the bug. This clears only the ones that bug could have caused: state ‘inaccessible’, a URI scheme the reader never fetches, and no validation ever recorded against it. They go back to ‘discovered’. Run it with –dry-run first; it prints what it would touch and changes nothing.

Option	What it does
--dry-run	list what would change and stop
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage evidence-fetch

A validation job refuses a remote URI on purpose: reaching the network from a job is a surprise on the machine it runs on. Its refusal says to fetch the document first and register where it landed, and this is the command that does that, run by you under your own network policy. SBOMs registered at an http or https URI are fetched, identified by content, stored under their hash in the uploads directory exactly as an upload is; the artifact keeps its URI and gains the hash, which is how the validator finds the copy. No credentials are sent. A fetch that fails marks the document ‘inaccessible’, which here means what it says: somebody tried and could not see, and the reason is recorded. Run it with –dry-run first. Then ‘crane validate sbom’.

Option	What it does
--dry-run	list what would be fetched and fetch nothing
--timeout SECONDS	how long to wait for each document (default 60)
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage repair-finding-variants

A finding written before 0.10.1 did not store the value that distinguishes it from another finding of the same code on the same subject – the profile, for a conformance check. Without it a portfolio measured against more than one profile exports a bundle that will not import, because those rows share one natural key. This recovers the value by recomputing each finding’s derived id over the candidates the installation actually has and keeping only the one that reproduces the id the row already carries, so a wrong answer cannot be written. A finding nothing reproduces is left alone. Run it with –dry-run first.

Option	What it does
--dry-run	list what would be recovered and stop
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage repair-claim-variants

A claim written before 0.10.2 did not store the value that distinguishes it from another claim of the same kind about the same subject – the profile, for a conformance verdict. Without it a product measured against three profiles exports one verdict instead of three, and the bundle imports cleanly while holding less than the portfolio did. This reads the profile from the claim’s own recorded value and accepts it only when it reproduces the dedupe key the row was written under, so a claim whose value and identity disagree is left alone. It also retires the conflicts left standing over the group those claims moved out of, including ones an earlier run of this command left behind, so it is worth running again on a database it has already repaired. Run it with –dry-run first.

Option	What it does
--dry-run	list what would be recovered and stop
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage claim

Two CRA checks read claims directly: support.period.declared wants a support.end_date claim and vuln.contact.published wants a vuln.contact claim. Lands as manual; the same fact arriving later in an import lands on the same row. The same operation is POST /api/v1/claims.

Option	What it does
--value-type string | number | boolean | date	—
--lens LENS	only for facts under one scope definition
--valid-from VALID_FROM	—
--valid-to VALID_TO	—
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage classify

code_bearing: built from source, so the product must reach a build. logical_bundle: an offering, SKU or rollup; build requirements apply to the code-bearing products and components it contains. externally_built and manual_process: no build of ours is expected. Recorded as an approved decision that outranks an import. Rescore for build.attributed to follow. The same operation is POST /api/v1/products/{id_or_slug}/implementation.

Option	What it does
--rationale RATIONALE	why: for a bundle, what it bundles; for an externally built product, who builds it
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage retract

With –valid-to the fact was true and stopped being; without it the claim is retracted and stays visible as retracted rather than deleted. The same operation is POST /api/v1/claims/{id}/end.

Option	What it does
--reason REASON	—
--valid-to VALID_TO	—
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage distribute

Published to a registry, consumed from one, shipped inside a device. Outbound is what places a product on the market, and not_distributed is a real channel: recording it outbound says ‘not distributed’ explicitly. Lands as manual; the same row in a distribution.csv lands on the same fact. The same operation is POST /api/v1/distribution.

Option	What it does
--locator LOCATOR	a purl or registry URL
--visibility public | customer | internal | unknown	—
--signed yes | no	leave off when nothing established it; that is not ‘no’
--note NOTE	—
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage depend

The upstream reference is kept verbatim even when the build is not tracked here, and the unresolved case raises MIG-004 like an import: a pipeline we depend on and cannot see is a coverage hole worth showing. The same operation is POST /api/v1/dependencies.

Option	What it does
--slug SLUG	the upstream build’s slug, when it is tracked here
--note NOTE	—
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage alias

An alias is what makes search find the thing under the name people actually use. Lands exactly like a row in aliases.csv. The same operation is POST /api/v1/aliases.

Option	What it does
--type TYPE	display, legacy, source_label, acronym or name
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage unalias

The row stays, marked removed: the record that the name was once used. What goes is its standing in search and matching. The same operation is POST /api/v1/aliases/{alias_id}/remove.

Option	What it does
--reason REASON	—
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage agent

codex, claude or copilot, installed and authenticated on this machine. Read only where this server runs the agent itself: by default interpret.agent is executed by a runner, the CLI lives there and is named in that runner’s [commands], and this is not consulted – the named consent is recorded against the runner’s token instead. A recorded choice either way, because non-interactive execution bypasses the tool’s own approval prompts. The same operation is POST /api/v1/settings/agent.

Option	What it does
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage own

Option	What it does
--role accountable | owning_organization | maintainer | security_contact | reviewer	only accountable counts for the no owner queue
--party-type person | team | organization | service	—
--email EMAIL	—
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage party

Option	What it does
--name NAME	the new display name. Import files matching on the old name will recreate it as a twin; update them too
--email EMAIL	an empty value clears it
--type person | team | service | organization	—
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage merge

Everything the duplicate holds moves to the keeper, an assignment the keeper already has supersedes the duplicate’s copy, and the duplicate is archived rather than deleted: its row is the record of the merge.

Option	What it does
--reason REASON	why these two are one party. The decision carries it
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage unit

The same rows an org_units.csv import writes, with the same derived identity, so neither makes twins of the other.

Option	What it does
--parent PARENT	the parent unit’s name
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage program

Off means: absent from the selector, not scored, its checks raise no work, its validation profiles stop being required. History stays — the policy is retired, never deleted, and scores already computed remain queryable. Inventory confidence refuses to turn off. See ‘crane policy list’ for the programs and their state.

Option	What it does
--reason REASON	why. Turning a program off changes every denominator at once
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage resolve

Writes an approved decision and a claim citing it, which outranks both sides and keeps winning across reimports. The sources keep disagreeing and the conflict stays visible as settled, which is the truth. Conflict ids: /api/v1/conflicts, or the scope page.

Option	What it does
--reason REASON	why this side is right
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage review

Option	What it does
--note NOTE	required to reject
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage except

Option	What it does
--queue QUEUE	an attention queue key
--check CHECK	a check inside an obligation policy
--reason REASON	at least eight characters
--expires EXPIRES	YYYY-MM-DD. Defaults to a year from today
--permanent	no expiry. Deliberately awkward to ask for
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage revoke

Option	What it does
--reason REASON	—
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage finding

Until this existed a finding could only ever be open, and the only way to make one stop appearing was to excuse it. Accepting a finding or calling it not applicable is a judgement and writes a decision; resolving one is an observation and does not.

Option	What it does
--note NOTE	why. Required for accepted and not_applicable
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage exceptions

Option	What it does
--status active | expired | revoked	—
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage identity

Option	What it does
--external-key EXTERNAL_KEY	—
--locator LOCATOR	a full URL for this one object
--object-type OBJECT_TYPE	what the source system calls this kind of thing, e.g. Service, Product, Project. It chooses the route a link is built from, so a catalogue that addresses several types alike needs it. Defaults to the subject type, which is a guess
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage define

A relationship type this deployment’s catalogue has and CRAne has no term for, a claim kind a feed carries. Until this existed the registry was reachable only from an adapter, so a deployment could load the value and not explain it – and the path that does check registration refused saying a migration had to declare it first. Registering restricts nothing: these columns are open vocabularies and stay open, so an unregistered value still loads. What it gains is a name and a meaning, which is what lets a page label it and what answers ‘what was this supposed to mean’ a year later. The same operation is POST /api/v1/vocabulary.

Option	What it does
--name DISPLAY_NAME	what to call it on screen
--description DESCRIPTION	what it means in the source system
--namespace NAMESPACE	defaults to ‘local’. ‘crane.core’ is reserved for what ships
--retire	stop offering the key while keeping the row, so data already carrying it stays explainable
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage definitions

Relationship types, claim kinds and the rest are open vocabularies, so what a key means lives only in the registry. The same listing is GET /api/v1/vocabulary.

Option	What it does
--class asset_type | channel_type | check_key | claim_kind | decision_type | environment | evidence_kind | obligation | org_level | platform_type | relationship_type | subject_type	—
--namespace NAMESPACE	—
--include-retired	—
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage identities

The read half of identity mapping. retype-identity and unidentify are addressed by the mapping’s id, which is derived from internal values and is not in an export, so this is where one comes from. Each row also carries the address the mapping currently resolves to, which is how a link pointing at the wrong kind of page is spotted without opening a browser. –generic lists only the mappings whose external type is just the subject type, which is the fallback applied when nothing named one. The same listing is GET /api/v1/identities.

Option	What it does
--system SYSTEM	restrict to one source system, by its key
--subject-type product | component | build_workflow | source_asset | party	—
--object-type OBJECT_TYPE	restrict to one kind of thing there, e.g. Service
--generic	only the mappings carrying the subject type as their external type, which is the population that needs correcting
--limit LIMIT	—
--offset OFFSET	—
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage retype-identity

A catalogue that exposes several entity types behind one address shape – a service, a product and a project, same host, same identifier format, one path segment apart – needs each mapping to carry the type it actually is, because that is what chooses the route. A mapping recorded without one carries the subject type instead, which is a guess. This is an operation rather than an edit because the identity’s id derives from the type: correcting the column in place leaves the row at an id no import will find, and the next one inserts a second mapping for the same object. The row moves, its recorded observations move with it, and a destination that already exists is merged into rather than duplicated. The same operation is POST /api/v1/identities/{id}/retype.

Option	What it does
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage unidentify

Marked deleted rather than removed, so which systems keep asserting things that turned out to be wrong stays answerable. The same operation is POST /api/v1/identities/{id}/remove.

Option	What it does
--by BY	who is making this change
--database DATABASE	—
--json	—

crane manage link

Option	What it does
--template TEMPLATE	containing {id}, {key} or {type}. Omit to clear
--label LABEL	—
--object-type OBJECT_TYPE	which kind the source system itself calls this, e.g. Service, Product, Project. A catalogue addressing several kinds one path segment apart needs a route for each, and they all arrive as one subject type here. Omit for the pattern that covers any kind, which is what a system addressing everything alike needs
--by BY	who is making this change
--database DATABASE	—
--json	—

crane report

Three reports, because a steering committee, an auditor, and the people doing the work want different documents rather than different sections of one. Run ‘crane report list’ to see them.

Option	What it does
--param NAME=VALUE	a parameter for a template, repeatable
--obligation OBLIGATION	obligation key, defaults to cra. See ‘crane policy list’
--format md | html | json	md for a file, html for something to send, json for a machine
--out PATH	write here instead of stdout
--note NOTE	a note recorded in an evidence package manifest
--json	machine readable summary

crane serve

Serves the interface. Binds to localhost by default: there is no authentication, so exposing it to a network is a decision to make deliberately.

Option	What it does
--host HOST	—
--port PORT	—
--worker	run a worker inside the web process. Required in a container nobody can shell into, since otherwise queued validations never execute