Notarizing

Notarizing documentation

CLI reference

Developer preview. Not yet production ready. This page is rendered from docs/cli-reference.md of the Notarizing repository at revision d23579e737f9d1e16e07b3c6b21a51282d64027e. It describes the behavior of that revision.

Contents

This file is the output of notarizing help and of notarizing help COMMAND for each command. A test makes it again from the binary and fails when a command is missing or its text is different. Do not edit this file by hand. Change the help text in internal/cli, then write the file again with the command in the comment above.

For the tasks that use these commands, read the user guide and the operator guide.

Commands

notarizing

notarizing [--workspace DIR] [--output text|json] COMMAND [flags] [arguments]

Notarizing is a local-first workspace for spec-driven review. The CLI
registers repositories, imports changes and evidence, reports what a change
promises and what was checked, and exports reviews and graphs. The browser
(notarizing serve) is the main review interface. notarizing mcp is a
read-only agent interface.

Commands:
  backup                   Write a consistent backup of the workspace to a new directory
  backup verify            Check a backup directory without changing it
  binding import           Import a notarizing.bindings/1 file of reviewed check bindings
  binding show             Show the active check bindings of a repository
  bundle export            Export retained evidence as a portable notarizing.bundle/1 archive
  bundle import            Import the evidence of a notarizing.bundle/1 archive
  change import            Import one change at an exact commit and index it
  change list              List the changes at a commit, or the imported changes
  change report            Report what a change requests, checked, failed, stale and unassessed
  compare                  Compare two imported targets at pinned review checkpoints
  doctor                   Check the workspace, its owner, Git, the browser assets and the provider
  evidence correct         Record that a later receipt retracts or corrects an earlier one
  evidence import          Import notarizing.check-report/1 reports and their declared artifacts
  evidence lookup          Find the local receipt of a report_id and report digest
  evidence show            Show one receipt: the collector record, the reported claim and its evaluations
  graph export             Export a bounded graph as Mermaid, Markdown or notarizing.graph/1 JSON
  graph query              Query a bounded dependency, impact, gaps or selection graph
  graph suggestions        List the similar-wording suggestions of the requirements of a target
  graph whatif             Show the claims that a draft change of assumptions potentially affects
  init                     Create a workspace, or migrate an existing one
  ka2a reload              Reload the broker TLS and SASL files of the running ka2a adapter
  mcp                      Serve read-only MCP tools on standard input and output
  policy set               Store a new version of the workspace assessment policy (notarizing.policy/1)
  policy show              Show the workspace assessment policy
  repo access restore      Restore the source access of a repository
  repo access revoke       Revoke the source access of a repository and invalidate its views
  repo add                 Register a local Git repository under an ID
  repo list                List the registered repositories
  repo set-path            Point a registered repository to a moved or new local checkout
  requirement history      Show the source revisions and the evidence history of one requirement
  retention apply          Apply a previewed purge plan
  retention preview        Preview a purge: the receipts, bytes and dependent views that it removes
  review export            Export the review of one change at a pinned review checkpoint as Markdown or JSON
  review patch             Export a wording draft as a proposal-only patch at an exact base commit
  review session grant     Give one browser session an expiring review grant
  review session list      List the open browser sessions of the running serve
  review session revoke    End the review grant of a browser session
  search                   Search specifications, declarations and review text
  search index             Build the lexical search index of a target, and optionally its semantic index
  search provider disable  Disable semantic search; search stays lexical
  search provider set      Enable the local Ollama embedding provider for hybrid search
  search provider show     Show the semantic provider configuration without contacting it
  search status            Show the search index generations of a target
  serve                    Own the workspace and serve the browser interface on 127.0.0.1
  version                  Print the version

Options before the command:
  --workspace DIR     workspace directory (default $NOTARIZING_WORKSPACE, else ./.notarizing)
  --output text|json  result format; json writes one notarizing.cli/1 document
  --version           print the version

Exit codes: 0 success, 1 failure, 2 usage error, 3 workspace busy,
4 unknown outcome (run the same command again), 5 unsupported,
130 interrupted.

Run notarizing help COMMAND for the flags of a command.

notarizing init

notarizing init [flags]

Create a workspace, or migrate an existing one

The command creates the workspace directory (mode 0700) and its database
(mode 0600). For an existing workspace, or a backup directory that you
restore, it takes ownership once and applies pending migrations. A new
workspace in a directory that holds other files is refused. A workspace with
a newer schema stays unchanged.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing doctor

notarizing doctor [flags]

Check the workspace, its owner, Git, the browser assets and the provider

The checks read the workspace files and the store read-only, look for a
running notarizing serve through the loopback control API of this workspace,
read the health of its optional ka2a adapter, and look for Git. The command
contacts no network service and no broker. Only with
--check-provider does it ask the configured local embedding provider for its
model digest. The exit code is 1 when a check has the status error.

Flags:
  --check-provider
        ask the configured local embedding provider for its model digest
  --output FORMAT
        result FORMAT: text or json
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing serve

notarizing serve [flags]

Own the workspace and serve the browser interface on 127.0.0.1

serve owns the workspace until you stop it (Ctrl-C). It listens on
127.0.0.1 only and prints the browser URL and a one-time viewer secret to
standard error. Paste the secret into the page. The page shows your browser
session ID; give it review authority with
  notarizing review session grant --session ID --ttl 30m --scope SCOPE
While serve runs, other notarizing commands send their imports through its
control API, and read commands read the workspace read-only. A stop ends
every session and grant.

serve writes log records to standard error: server errors, a background
service that stops with an error and a shutdown that does not finish in
time. --log-level selects the lowest level (debug, info, warn or error;
the default is info). --log-format selects text (the default) or json.
A log record never holds a secret, a token, a request body, a query or
source text.

With --ka2a-config FILE, serve also runs the optional ka2a adapter
(evidence-over-ka2a/1) with the ka2a node of that configuration. Its health
is separate: a broker outage never stops serve or the local workspace.
Without the flag, serve opens no broker connection. With the flag, SIGHUP
reloads the broker TLS and SASL files, like notarizing ka2a reload.

Flags:
  --ka2a-config FILE
        enable the optional ka2a adapter with the configuration FILE
  --log-format FORMAT
        FORMAT of the log records on standard error: text or json (default text)
  --log-level LEVEL
        lowest LEVEL of the log records on standard error: debug, info, warn or error (default info)
  --open
        open the browser URL with the system browser
  --port PORT
        browser PORT on 127.0.0.1; 0 selects a free port (default 7373)
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing mcp

notarizing mcp [flags]

Serve read-only MCP tools on standard input and output

The MCP server opens the workspace read-only, so it works while notarizing
serve owns the workspace. It never migrates, writes, imports, purges,
builds an index, configures a provider or runs a tool. Search is lexical only.
Every response is bounded, names its target and coverage, and says that
repository, report and review text is untrusted data.

At the end of standard input, the server answers the requests that it already
read and exits 0. A stop signal or the end of input starts a grace of 2s.
When the grace ends before every answer is written, the process exits 1.

Flags:
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing version

notarizing version [flags]

Print the version

Flags:
  --output FORMAT
        result FORMAT: text or json

notarizing repo add

notarizing repo add [flags] ID PATH

Register a local Git repository under an ID

ID is your name for the repository: lower-case letters, digits, ".",
"_" and "-", at most 64 characters. PATH is the local repository directory.
Notarizing reads exact Git objects from it. It never writes to it, fetches
or runs hooks. While notarizing serve owns the workspace, the command goes
through its control API. If the checkout moves later, run notarizing repo
set-path ID PATH.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing repo set-path

notarizing repo set-path [flags] ID PATH

Point a registered repository to a moved or new local checkout

Use the command when the local checkout of a registered repository moved or
was cloned again. PATH follows the rules of repo add. Before it records the
change, the command checks that PATH is a Git repository with the registered
object format and that it contains the latest imported commit of the
repository. Otherwise it changes nothing and fails with conflict.

The change is recorded with the previous path, the checked commit, the time
and the caller. Stored snapshots, targets, receipts and review records do not
change. The same path again records nothing. While the source access of the
repository is revoked, the command is refused. While notarizing serve owns
the workspace, the command goes through its control API.

There is no repo remove: stored history references the repository ID. To
stop every view of a repository, use notarizing repo access revoke.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing repo list

notarizing repo list [flags]

List the registered repositories

Flags:
  --output FORMAT
        result FORMAT: text or json
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing repo access revoke

notarizing repo access revoke [flags] ID

Revoke the source access of a repository and invalidate its views

Source access says whether notarizing may read the stored source of a
registered repository. Revoke it when the workspace may no longer show the
content of the repository, for example after the repository moved to a
restricted host. Restore it when access is approved again.

The change, a new source access generation and the invalidation of every
search index commit in one transaction. Cached graph and review views are
dropped. While access is revoked, the browser, MCP, the change report and the
CLI refuse every view that reads the stored source of the repository with
forbidden, search finds none of its text, and change import, change list --at
and search index refuse to read it. A search index build that read the source
before the revocation stores nothing. bundle export --target refuses a target
of the repository, because review events quote its source. Stored snapshots,
receipts and review records stay. Search indexes of other repositories are
invalidated too; rebuild them with notarizing search index. After a restore,
rebuild the search indexes of the repository.

The same request again records nothing. Only the CLI changes source access,
directly or through the running owner; the browser, MCP and ka2a producers
cannot.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --reason TEXT
        TEXT of at most 500 bytes that says why
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing repo access restore

notarizing repo access restore [flags] ID

Restore the source access of a repository

Source access says whether notarizing may read the stored source of a
registered repository. Revoke it when the workspace may no longer show the
content of the repository, for example after the repository moved to a
restricted host. Restore it when access is approved again.

The change, a new source access generation and the invalidation of every
search index commit in one transaction. Cached graph and review views are
dropped. While access is revoked, the browser, MCP, the change report and the
CLI refuse every view that reads the stored source of the repository with
forbidden, search finds none of its text, and change import, change list --at
and search index refuse to read it. A search index build that read the source
before the revocation stores nothing. bundle export --target refuses a target
of the repository, because review events quote its source. Stored snapshots,
receipts and review records stay. Search indexes of other repositories are
invalidated too; rebuild them with notarizing search index. After a restore,
rebuild the search indexes of the repository.

The same request again records nothing. Only the CLI changes source access,
directly or through the running owner; the browser, MCP and ka2a producers
cannot.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --reason TEXT
        TEXT of at most 500 bytes that says why
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing change list

notarizing change list [flags]

List the changes at a commit, or the imported changes

With --at, the command resolves LOCATOR (a full branch or tag name, a short
branch name or a full commit ID) in the repository and lists the change
directories at that commit. Archived changes are listed apart: they are
history, not current intent. Without --at, the command lists the imported
changes (targets) of the workspace, oldest import first.

Flags:
  --at LOCATOR
        LOCATOR: a branch, a tag or a full commit ID; HEAD is not accepted
  --output FORMAT
        result FORMAT: text or json
  --repo ID
        repository ID
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing change import

notarizing change import [flags]

Import one change at an exact commit and index it

The command resolves LOCATOR to an exact commit, reads the OpenSpec files of
the change (or of the accepted specifications only, without --change),
builds the effective target and stores it. Then it builds the lexical search
index of the target. An import is idempotent: the same repository, commit,
change and extractor give the stored target again. A branch that moves later
does not change a stored target. An unresolvable locator stores nothing; there
is no fallback to another revision.

Flags:
  --at LOCATOR
        LOCATOR: a branch, a tag or a full commit ID; HEAD is not accepted
  --change NAME
        change NAME; empty imports the accepted specifications only
  --output FORMAT
        result FORMAT: text or json
  --repo ID
        repository ID
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing change report

notarizing change report [flags]

Report what a change requests, checked, failed, stale and unassessed

The report lists every effective requirement of one imported change with its
exact source, its assessment rows (the reported claim beside the evaluated
status), its missing dimensions, and the declared assumptions, premise groups,
open questions, review findings and extractor diagnostics, with review states
at one review checkpoint. It works before any check report exists: a
requirement without a binding or a report stays visible as unassessed. It
never gives an overall pass badge. Name the change with --target, or with
--repo and --change for the latest import of the change. The command reads the
workspace read-only; it works while notarizing serve runs.

Flags:
  --change NAME
        change NAME, with --repo; the latest import of the change
  --checkpoint CHECKPOINT
        review CHECKPOINT: a sequence number or latest (default latest)
  --format FORMAT
        report FORMAT: text, json or markdown (default text; json with --output json)
  --output FORMAT
        result FORMAT: text or json
  --repo ID
        repository ID, with --change
  --target ID
        target ID (tgt_...) of an imported change
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing requirement history

notarizing requirement history [flags] REQUIREMENT-ID

Show the source revisions and the evidence history of one requirement

The history follows the stable Requirement-ID across imports, also across a
heading rename. A requirement without a Requirement-ID has only a provisional
identity and no history across snapshots. The evidence history lists every
receipt whose report names the requirement, newest first, with the reported
claim beside its evaluation under the current policy.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --repo ID
        repository ID
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing binding import

notarizing binding import [flags] FILE

Import a notarizing.bindings/1 file of reviewed check bindings

A binding links a requirement to an approved check with its required
configurations. Only this command creates bindings: a declared Evaluated-By
link, a review decision or a report never does. The exact file bytes are the
identity of the import; the same bytes again return the same import.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing binding show

notarizing binding show [flags]

Show the active check bindings of a repository

Flags:
  --history
        also list every binding import, oldest first
  --output FORMAT
        result FORMAT: text or json
  --repo ID
        repository ID
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing policy set

notarizing policy set [flags] FILE

Store a new version of the workspace assessment policy (notarizing.policy/1)

The policy names the trusted source namespaces with their methods and the
reviewed not_applicable exclusions. A local file import is manual_unverified:
its reported outcome counts only when the policy trusts its source. The
browser can never change the policy.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing policy show

notarizing policy show [flags]

Show the workspace assessment policy

Flags:
  --output FORMAT
        result FORMAT: text or json
  --version VERSION
        policy VERSION; -1 shows the current version (default -1)
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing evidence import

notarizing evidence import [flags] [REPORT.json...]

Import notarizing.check-report/1 reports and their declared artifacts

Each report is validated strictly and every declared artifact is read only
below its artifact directory, with its declared length and SHA-256. A bad
artifact rejects the whole report. A local file import is attributed as
manual_unverified: the change report shows a reported pass as "not
independently established" unless the policy trusts the local source.
The command never runs, opens or fetches anything that a report names. The
same report again returns the same receipt; the same report_id with other
bytes is a conflict.

The command takes 1 to 256 report files. --artifacts DIR names the artifact
directory of every report. --dir DIR imports DIR/NAME/report.json of each
subdirectory of DIR, in name order, with that subdirectory as its artifact
directory: the output layout of gotestreport. --dir takes no report file and
no --artifacts.

Each report is imported alone, with its own receipt. With several reports, a
failed report does not stop the others. The result then lists each file with
its status: accepted, failed or not_attempted (after an interruption). If a
report is not accepted, the command fails with exit code 4 when an outcome is
unknown (run the same command again; accepted reports return the same
receipts), or else with the exit code of the first failed report.

A lexical index holds the summaries of the reports at its commit, so the
import makes the index of each target at the requirement snapshot of a
report stale. The command then rebuilds those stale indexes, at most 16. A
failed rebuild is a warning; the receipts stay. Use --no-index for a bulk
import, and run notarizing search index once at the end.

Flags:
  --artifacts DIR
        DIR that holds the declared artifacts of every report
  --dir DIR
        DIR with one subdirectory per report, as gotestreport writes it
  --no-index
        do not rebuild the search indexes that the import makes stale
  --output FORMAT
        result FORMAT: text or json
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing evidence show

notarizing evidence show [flags] RECEIPT-ID

Show one receipt: the collector record, the reported claim and its evaluations

The three parts stay apart: the receipt is what the workspace accepted, the
reported claim is what the producer asserts, and the evaluations are what the
claim establishes under the current policy. Report text is untrusted data.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing evidence lookup

notarizing evidence lookup [flags]

Find the local receipt of a report_id and report digest

Lookup is for reconciliation after a lost response: it finds the receipt of
the local source for a report_id, only for the exact report digest. Another
digest is a conflict.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --report-id ID
        producer report ID (a UUID)
  --sha256 HEX
        SHA-256 HEX of the exact report bytes
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing evidence correct

notarizing evidence correct [flags]

Record that a later receipt retracts or corrects an earlier one

A producer cannot change a report: check-report/1 is frozen and a receipt is
never changed. To retract or correct an earlier result, the producer submits a
new report, and the operator records the relation between the two receipts.

Both receipts must exist, come from the same source and report the same check
and requirement. The correcting receipt must be the later one. A receipt is
corrected at most once; the same command again returns the first record.

Both receipts stay, with their own attribution. The correction does not change
an assessment and does not retire a failure: only a reviewed supersession can.
evidence show, requirement history, the change report and MCP show the
correction. Only the CLI records corrections, directly or through the running
owner; the browser, MCP and ka2a producers cannot.

Flags:
  --corrected ID
        receipt ID of the earlier, corrected result
  --correcting ID
        receipt ID of the later, correcting result
  --output FORMAT
        result FORMAT: text or json
  --reason TEXT
        TEXT of at most 500 bytes that says why
  --relation RELATION
        RELATION: retracts or corrects
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing review session grant

notarizing review session grant [flags]

Give one browser session an expiring review grant

The session ID is the ID that the browser shows (ses_...). A reviewer can
append review notes, decisions, proposals and wording drafts inside the scope
until the grant expires or you revoke it. A grant never allows imports,
policy or binding changes, purges, provider changes or source edits.
SCOPE is workspace, repo:<repository_id> or change:<repository_id>/<change>.
The time to live is 1 minute to 8 hours. A restart of serve ends every grant.
Use --actor LABEL to name the reviewer in review events and exports.
Notarizing does not verify the label. Events show it as "LABEL (unverified,
browser session XXXX)". The label never changes what the grant allows.
The command needs the running notarizing serve.

Flags:
  --actor LABEL
        unverified display LABEL of the reviewer, 1 to 28 characters
  --output FORMAT
        result FORMAT: text or json
  --scope SCOPE
        grant SCOPE: workspace, repo:ID or change:REPO/CHANGE
  --session ID
        browser session ID (ses_...)
  --ttl DURATION
        time to live DURATION, 1m to 8h (default 30m0s)
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing review session revoke

notarizing review session revoke [flags]

End the review grant of a browser session

The session stays open as a viewer. The command needs the running
notarizing serve.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --session ID
        browser session ID (ses_...)
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing review session list

notarizing review session list [flags]

List the open browser sessions of the running serve

The list has no secret: no cookie, no CSRF token and no viewer secret.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing review export

notarizing review export [flags]

Export the review of one change at a pinned review checkpoint as Markdown or JSON

The export pins one target and one review checkpoint: later review events do
not change it. "latest" reads the latest checkpoint first and pins that number.
The document holds the exact sources, the requirements, the assumptions with
their review states, the premise groups, the open questions, the relationships
under review, the notes, the wording drafts, the diagnostics and the limits.
Without --output, the document goes to standard output.

Flags:
  --change NAME
        change NAME, with --repo
  --checkpoint CHECKPOINT
        review CHECKPOINT: a sequence number or latest (required)
  --force
        replace an existing output file
  --format FORMAT
        document FORMAT: markdown or json (default markdown)
  --output FILE
        write the document to FILE
  --repo ID
        repository ID, with --change
  --target ID
        target ID (tgt_...) of an imported change
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing review patch

notarizing review patch [flags]

Export a wording draft as a proposal-only patch at an exact base commit

The patch replaces the complete requirement block of the draft and keeps every
other byte of the file. It is computed from stored source bytes only: the
command never reads or writes the repository, runs git, commits or pushes.
A base file that differs from the file of the draft is a conflict (base
changed). The command writes the patch to FILE and its manifest (base,
edits, proposal_only status) to FILE.manifest.json. Review the patch against
your working tree before you apply it.

Flags:
  --base SHA
        full base commit SHA
  --draft ID
        draft ID: the event ID of a wording.propose event
  --force
        replace existing output files
  --output FILE
        write the patch to FILE (required)
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing graph query

notarizing graph query [flags]

Query a bounded dependency, impact, gaps or selection graph

dependencies follows depends_on, assumes and member relationships from the
roots. impact follows them in reverse. selection follows every relationship.
gaps lists the requirements without approved coverage and the assumptions
without review near the roots. A view is bounded; its coverage says what it
omits, and --continue reads the next page. A graph is a review aid: its
reachability never establishes correctness.

Flags:
  --checkpoint CHECKPOINT
        review CHECKPOINT: a sequence number or latest (default latest)
  --continue TOKEN
        continuation TOKEN of an earlier page of the same query
  --depth STEPS
        traversal STEPS from the roots, 0 to 4 (default 1)
  --format FORMAT
        result FORMAT: text or json (default text; json with --output json)
  --max-edges LIMIT
        edge LIMIT, 0 to 1000 (default 300)
  --max-nodes LIMIT
        node LIMIT, 1 to 500 (default 150)
  --object ID
        root ID: an object ID or a stable ID such as a Requirement-ID (repeatable, 1 to 20)
  --output FORMAT
        result FORMAT: text or json
  --suggestions
        include machine suggestions (never followed as dependencies)
  --target ID
        target ID (tgt_...) of an imported change
  --view VIEW
        VIEW: dependencies, impact, gaps or selection (default selection)
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing graph suggestions

notarizing graph suggestions [flags]

List the similar-wording suggestions of the requirements of a target

The generator notarizing.suggest/1 compares the wording of the requirements
of the target in the stored search index. The lexical method always runs. The
embedding method runs only when the local provider is enabled and a verified
semantic index of its profile exists; it uses the stored vectors and never
calls the provider. Build the index first with "notarizing search index".
A suggestion is an unreviewed may_relate proposal. It is no dependency,
binding, coverage or review state. Scores are similarities, not confidence.
A reviewer can turn a suggestion into a review record in the browser.

Flags:
  --format FORMAT
        result FORMAT: text or json (default text; json with --output json)
  --object ID
        keep only the suggestions of this object: an object ID or a stable ID
  --output FORMAT
        result FORMAT: text or json
  --target ID
        target ID (tgt_...) of an imported change
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing graph export

notarizing graph export [flags]

Export a bounded graph as Mermaid, Markdown or notarizing.graph/1 JSON

The export pins one target and one review checkpoint; "latest" (the default)
reads the latest checkpoint and pins that number. The same target, checkpoint,
filters and exporter give the same bytes. With --view FILE, the command
decodes a saved notarizing.graph/1 JSON file strictly and re-exports it in the
requested format; that is a presentation only and needs no workspace.
Without --output, the document goes to standard output.

Flags:
  --checkpoint CHECKPOINT
        review CHECKPOINT: a sequence number or latest (default latest)
  --depth STEPS
        traversal STEPS from the roots, 0 to 4 (default 1)
  --force
        replace an existing output file
  --format FORMAT
        document FORMAT: mermaid, markdown or json (required)
  --max-edges LIMIT
        edge LIMIT, 0 to 1000 (default 300)
  --max-nodes LIMIT
        node LIMIT, 1 to 500 (default 150)
  --object ID
        root ID: an object ID or a stable ID such as a Requirement-ID (repeatable, 1 to 20)
  --output FILE
        write the document to FILE
  --suggestions
        include machine suggestions (never followed as dependencies)
  --target ID
        target ID (tgt_...) of an imported change
  --view VIEW
        VIEW: dependencies, impact, gaps or selection, or a notarizing.graph/1 JSON FILE to re-export (default selection)
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing graph whatif

notarizing graph whatif [flags]

Show the claims that a draft change of assumptions potentially affects

A what-if draft removes or replaces assumptions in a copy of the graph.
The result lists the claims that are potentially affected under recorded
dependencies and the premise groups that change. A removed member of an
all_of group is a lost required premise. A replacement changes the
statement only: it keeps the scope and category of the assumption and
starts open, because a changed statement needs a new review decision.
The draft exists only for this command. It changes no source snapshot and
no review record, and it does not invalidate historic evidence. A graph is
a review aid: it does not find every real effect.

Flags:
  --checkpoint CHECKPOINT
        review CHECKPOINT: a sequence number or latest (default latest)
  --depth STEPS
        impact STEPS from the changed assumptions, 0 to 4 (default 2)
  --draft ID
        draft ID: a name for this draft in the result (default cli-draft)
  --format FORMAT
        result FORMAT: text or json (default text; json with --output json)
  --max-edges LIMIT
        edge LIMIT, 0 to 1000 (default 300)
  --max-nodes LIMIT
        node LIMIT, 1 to 500 (default 150)
  --output FORMAT
        result FORMAT: text or json
  --remove ID
        remove the assumption ID in the draft (repeatable)
  --replace ID=TEXT
        replace the statement of an assumption: ID=TEXT (repeatable)
  --suggestions
        include machine suggestions (never followed as dependencies)
  --target ID
        target ID (tgt_...) of an imported change
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing compare

notarizing compare [flags]

Compare two imported targets at pinned review checkpoints

Rows match only by stable ID. A provisional requirement is never matched: it
stays its own row. Requirements, assumptions, premise groups, relationships
and review decisions stay separate aspects. The command reads the workspace
read-only. It does not compute evidence applicability; run change report on
each target for the assessment.

A relationship is a declared claim: its kind, its endpoints, its origin and
its scope. A declaration that moved to other source lines is not a change;
the counts and the JSON output show such provenance differences. The text
output names objects by stable ID and label. The JSON output also has the
object IDs.

Flags:
  --format FORMAT
        result FORMAT: text or json (default text; json with --output json)
  --left ID
        left target ID (tgt_...)
  --left-checkpoint CHECKPOINT
        review CHECKPOINT of the left side: a number or latest (default latest)
  --output FORMAT
        result FORMAT: text or json
  --right ID
        right target ID (tgt_...)
  --right-checkpoint CHECKPOINT
        review CHECKPOINT of the right side: a number or latest (default latest)
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)
notarizing search [flags]

Search specifications, declarations and review text

An exact Requirement-ID or declaration ID comes first. Then come lexical
FTS5 results. --mode hybrid also ranks with the explicitly configured local
embedding provider; a provider problem gives lexical results with a warning.
The default corpus is the latest import of each change; --historical adds
older revisions, labeled historical. A missing or stale index shows as
coverage pending, partial or stale, never as "no match". The query is
sensitive: it never goes into the output or an error. Shell history can keep
--query; use --query-stdin for sensitive text.

Flags:
  --historical
        include older revisions, labeled historical
  --kind KIND
        object KIND to include (repeatable): requirement, assumption, decision, question, component, check, model, premise_group, document, review_note or check_summary
  --limit LIMIT
        result LIMIT, 1 to 100 (default 50)
  --mode MODE
        MODE: lexical or hybrid (default lexical)
  --output FORMAT
        result FORMAT: text or json
  --query TEXT
        query TEXT, at most 2048 bytes
  --query-stdin
        read the query from standard input
  --snapshot ID
        search every target of one snapshot ID (snap_...)
  --target ID
        search one target ID (tgt_...)
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing search status

notarizing search status [flags]

Show the search index generations of a target

Flags:
  --output FORMAT
        result FORMAT: text or json
  --target ID
        target ID (tgt_...)
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing search index

notarizing search index [flags]

Build the lexical search index of a target, and optionally its semantic index

The lexical build reads the stored target and the retained reports; it never
reads the repository. --semantic then embeds the chunks with the configured
local provider (notarizing search provider set). It never downloads a model
and never calls a hosted service. A purge or a new index during the build
discards late vectors.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --semantic
        also build the semantic index with the enabled provider
  --target ID
        target ID (tgt_...)
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing search provider set

notarizing search provider set [flags]

Enable the local Ollama embedding provider for hybrid search

The endpoint must be a literal loopback address, for example
http://127.0.0.1:11434. The model must already be installed; pin its digest
as /api/tags reports it. The command makes no network call and never
installs or updates a model. A local model service is a separate process that
can keep its own copies of inputs.

Flags:
  --digest SHA256
        pinned model digest: SHA256 hex
  --dimension DIMENSION
        vector DIMENSION, 1 to 4096 (default 0)
  --endpoint URL
        loopback URL, for example http://127.0.0.1:11434
  --model NAME
        installed model NAME
  --output FORMAT
        result FORMAT: text or json
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing search provider disable

notarizing search provider disable [flags]

Disable semantic search; search stays lexical

Flags:
  --output FORMAT
        result FORMAT: text or json
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing search provider show

notarizing search provider show [flags]

Show the semantic provider configuration without contacting it

Flags:
  --output FORMAT
        result FORMAT: text or json
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing retention preview

notarizing retention preview [flags] SELECTOR...

Preview a purge: the receipts, bytes and dependent views that it removes

A SELECTOR term is receipt:ID, artifact:SHA256, source:NAMESPACE or
before:RFC3339-TIME. Every term must match. The preview changes nothing.
Write the plan with --output FILE and apply it with notarizing retention apply
--plan FILE. A purge makes content unavailable to every query; it does not
promise forensic erasure of earlier backups, file system copies or external
services.

Flags:
  --force
        replace an existing plan file
  --output FILE
        write the plan to FILE for retention apply
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing retention apply

notarizing retention apply [flags]

Apply a previewed purge plan

The command recomputes the plan in its write transaction. A plan whose digest
no longer matches the workspace is stale_revision, and nothing changes: preview
again. A purge keeps a tombstone without content for each receipt and
invalidates every search generation. It never touches a repository, a source
snapshot, a target or a review record.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --plan FILE
        plan FILE of retention preview --output
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing backup

notarizing backup [flags]

Write a consistent backup of the workspace to a new directory

The backup directory holds workspace.db (a consistent copy of the live pages)
and backup.json (the manifest with digests). The directory must not exist.
Check a backup with notarizing backup verify DIR. To restore, copy the backup
directory, run notarizing init --workspace COPY once, and use COPY as the
workspace.

Flags:
  --output DIR
        new backup DIR (required)
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing backup verify

notarizing backup verify [flags] DIR

Check a backup directory without changing it

The check decodes the manifest strictly, compares the database digest and
length, and opens the database read-only for its schema, integrity and foreign
keys. It needs no workspace.

Flags:
  --output FORMAT
        result FORMAT: text or json

notarizing bundle export

notarizing bundle export [flags]

Export retained evidence as a portable notarizing.bundle/1 archive

Select receipts with --target (reports about the repository and commit of the
target), --receipt and --source; every given selector must match. The bundle
holds the exact report and artifact bytes, the receipts as attributed
historical records, the source target references and explicit omissions. The
file must not exist. The command reads the workspace read-only.

Flags:
  --output FILE
        new bundle FILE (required)
  --receipt ID
        select a receipt ID (repeatable)
  --source NAMESPACE
        select a source NAMESPACE
  --target ID
        select the reports of a target ID (tgt_...)
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing bundle import

notarizing bundle import [flags] FILE

Import the evidence of a notarizing.bundle/1 archive

The import checks the archive structure, the manifest, every digest and
length and every report before it writes, and then stores all receipts or
nothing. Imported receipts get the attribution imported_bundle and a new
local receipt ID; the original receipts stay attributed historical claims.
A trust policy for the original source does not apply to them. Review
events and corrections of the bundle stay claims of the exporting workspace:
they change no local review state, assessment or policy.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

notarizing ka2a reload

notarizing ka2a reload [flags]

Reload the broker TLS and SASL files of the running ka2a adapter

The running notarizing serve reads the TLS files (ca_file, cert_file,
key_file, crl_file) and the SASL password_file of its ka2a adapter
configuration again, with the checks of the start; a stale or untrusted
revocation list is refused. The ka2a node checks the new material
with one broker request before it uses it. Each new broker connection then
uses the new material. Work in flight does not change, and serve does not
restart. On a refusal, the adapter keeps the previous material and the
command fails. The other fields of the configuration file stay until a
restart of serve. SIGHUP to serve --ka2a-config does the same reload.
The adapter health (notarizing doctor) shows the last reload result.

Flags:
  --output FORMAT
        result FORMAT: text or json
  --workspace DIR
        workspace DIR (default $NOTARIZING_WORKSPACE, else ./.notarizing)

All Notarizing documents