McPherson AI
Observa help · CLI reference

Every supported Observa Local Node command.

This documents @mcpherson-ai/observa-local-node 0.1.6. Run observa --help for the same command list from the binary you actually have installed.

SHADOW_ONLY · AUTHORITY NONE · ENFORCEMENT OFF — Observa observes and reports. It has no authority to allow, deny, approve, block, retry, or change anything in your systems.

How to read this page

Syntax lines versus commands you can paste

  • Syntax lines use angle-bracket placeholders such as <https://host> and square brackets for optional flags. They are grammar, not commands — do not paste them.
  • Example lines are literal and copy/pasteable as written, against the current Hosted beta service https://governance-plane-observa.tailb473db.ts.net.
  • Exit status is 0 on success, 1 on a refusal, and 2 for an unrecognized command. Asking for help is a success.
  • Every refusal prints REFUSED <CODE>. Refusals with a documented recovery also print a link to the troubleshooting page.
  • OBSERVA_HOME overrides the installation home (default ~/.observa/installation). OBSERVA_TRUST_DIR overrides the verification key directory.
Read-only

Inspection commands

None of these write anything, and none of them contact Hosted.

observa status

Non-secret facts about this installation.

Syntax

observa status [--json]

Example

observa status
Changes locally
Nothing. Read-only.
Contacts Hosted
No — a configured pairing is reported as configured, never probed.
Safety
Reports config key presence only. No config value, credential or pairing code can reach this output.

observa inspect-workflow

Static, offline structure inspection of one n8n workflow export. Available before you have any access.

Syntax

observa inspect-workflow --file <n8n-workflow.json> [--json]

Example

observa inspect-workflow --file ./workflow.json
Changes locally
Nothing. Reads the one file you named and writes nothing.
Contacts Hosted
No
Safety
Prints no node names, IDs, parameters, credentials or payloads. Unrecognized node types are counted, never echoed. It does not observe execution, classify capabilities, evaluate policy, establish trust, or grant access.

observa activity

Recent local SHADOW observations from the owner-only evidence journal.

Syntax

observa activity [--limit <1-100>]

Example

observa activity --limit 50
Changes locally
Nothing. Read-only.
Contacts Hosted
No
Safety
Reads a hash-chained, owner-only local journal; a broken chain refuses rather than printing partial history. Default limit 20.

observa decisions

Local counterfactual records only — entries that were actually evaluated and carry a sealed decision record.

Syntax

observa decisions [--limit <1-100>]

Example

observa decisions
Changes locally
Nothing. Read-only.
Contacts Hosted
No
Safety
Activity never becomes a decision. Values are WOULD_ALLOW, WOULD_DENY, WOULD_REQUIRE_APPROVAL, ABSTAIN, INDETERMINATE, ERROR — all counterfactual.

observa agents

Agent view.

Syntax

observa agents [--json]

Example

observa agents
Changes locally
Nothing. Read-only.
Contacts Hosted
No
Safety
On this runtime it always returns an empty list plus an explicit limitation: n8n provides no real agent identity through this integration. The emptiness is a stated limitation, not a finding of “no agents”.

observa agent <id>

Single-agent view.

Syntax

observa agent <id> [--json]

Example

observa agent my-agent
Changes locally
Nothing. Read-only.
Contacts Hosted
No
Safety
Same limitation as agents: on the n8n path there is no agent identity to resolve, so the id is accepted and the limitation is printed.

observa diagnose

Integrity, signature, configuration-presence and permission checks. The first command to run when something is wrong.

Syntax

observa diagnose

Example

observa diagnose
Changes locally
Nothing. Read-only.
Contacts Hosted
No — connectivity is reported as INFO, not probed.
Safety
Exits 1 if any check FAILs. Output is paste-safe: every check reports presence or shape, never a value. Include it in a support request.

observa version

Print the version and authority banner.

Syntax

observa version | observa --version

Example

observa --version
Changes locally
Nothing.
Contacts Hosted
No
Safety
—
Local state

Installation and runtime commands

observa install

Verify a signed installation manifest and compose exactly the approved component artifacts it names.

Syntax

observa install [--manifest <signed.json>] [--artifacts <dir>] [--expect-installation <id>]

Example

observa install
Changes locally
Creates the release tree, artifact cache, manifest store, state.json and the current symlink under ~/.observa/installation (override with OBSERVA_HOME). Touches nothing else.
Contacts Hosted
Yes when --manifest is omitted — it retrieves the manifest Hosted issued for this paired installation. No with --manifest.
Safety
Both paths use one verifier: strict parse, closed schema, Ed25519 signature against the public key shipped in the package, tenant and installation binding, then every artifact by manifest-pinned SHA-256. Transport is not trust. The only accepted mode is SHADOW_ONLY; a manifest asking for anything else fails closed at schema validation.

observa update

Install a strictly newer signed manifest, retaining the current release for rollback.

Syntax

observa update [--manifest <signed.json>] [--artifacts <dir>]

Example

observa update --manifest ./observa-manifest.signed.json
Changes locally
Stages the new release beside the old one and moves current. The previous manifest id is retained.
Contacts Hosted
Yes when --manifest is omitted.
Safety
Refuses NOT_INSTALLED without an existing installation and MANIFEST_NOT_NEWER_THAN_CURRENT for anything not strictly newer. A failed update leaves the existing installation intact.

observa rollback

Return to the retained previous signed manifest.

Syntax

observa rollback

Example

observa rollback
Changes locally
Moves current back to the previous release, rewrites state.json, and clears the previous-manifest pointer. If the retained tree fails integrity it is rebuilt offline from the verified artifact cache.
Contacts Hosted
No — fully offline.
Safety
Refuses ROLLBACK_TARGET_ABSENT when there is nothing to roll back to. Rollback is single-depth: after rolling back there is no further previous release.

observa start

Start Observa’s own local observer service.

Syntax

observa start [--port <port>]

Example

observa start
Changes locally
Writes a pidfile under the installation’s service directory and spawns the verified adapter from the active release.
Contacts Hosted
Yes when paired — this is what delivers SHADOW_ONLY evidence to your workspace.
Safety
Starts only Observa’s own process, from the active verified release.

observa stop

Stop Observa’s own local observer service.

Syntax

observa stop

Example

observa stop
Changes locally
Signals the pid from Observa’s own pidfile and removes it.
Contacts Hosted
No
Safety
Structurally cannot stop anything else. The only process it will signal is one whose pid came from Observa’s pidfile and whose command line still names the Observa release path. There is no search-by-name, no pkill, and no port scan. It never stops your n8n.

observa uninstall

Remove Observa-managed state from this machine.

Syntax

observa uninstall --yes [--purge-config]

Example

observa uninstall --yes
Changes locally
Stops the service, then removes the releases, artifact cache, manifest store, service directory, current symlink and state.json. Your local config survives by default; --purge-config removes it too.
Contacts Hosted
No — it does not revoke a Hosted credential. Run unpair first if you want delivery revoked.
Safety
Refuses without --yes. Removing state locally does not revoke anything server-side.

observa config set

Set one local configuration value. These are yours and stay on this machine.

Syntax

observa config set <key> <value>

Example

observa config set n8n_loopback_credential '<choose any local secret, 24+ characters>'
Changes locally
Writes the owner-only config file at ~/.observa/installation/config/local.json.
Contacts Hosted
No
Safety
The value is never echoed back, never logged, never diagnosed and never placed in a manifest or artifact. Keys the pairing flow owns are refused here with HOSTED_CONFIG_PAIRING_OWNED — use observa pair.

observa n8n-setup

Write the owner-only environment file for n8n’s supported global backend hook.

Syntax

observa n8n-setup

Example

observa n8n-setup
Changes locally
Copies the packaged hook into the installation and writes an owner-only .env-style file, then prints its path.
Contacts Hosted
No
Safety
It does not start, restart or reconfigure n8n, and it edits no workflow. Loading that environment file into your n8n service is your step. Requires an installation and a configured n8n_loopback_credential of at least 24 characters.
Hosted

Access and pairing commands

These are the only commands that talk to a Hosted service, and only to the one you named. Full lifecycle detail is on the pairing and access page.

observa request-access

Submit, verify or resend a Hosted beta access request. Submitting is not being granted access.

Syntax

observa request-access --api-url <https://host> [--name <name>] [--email <email>]
                       [--organization <org>] [--use-case <text>]
                       [--code-file <0600-file>] [--resend] [--new] [--yes] [--json]

Example

observa request-access --api-url https://governance-plane-observa.tailb473db.ts.net
Changes locally
Writes an owner-only private receipt at ~/.observa/installation/observa-access/request.json. That receipt, not the request id, is what authenticates you later.
Contacts Hosted
Yes
Safety
Shows you the exact record before sending and requires you to type yes (or pass --yes). Verification codes and request credentials never appear in --json output. Requires verified TLS; a NODE_TLS_REJECT_UNAUTHORIZED override refuses the command. Identity is immutable after submission — a different email needs a new verified request.

observa request-status

Check the state of the request saved for this profile.

Syntax

observa request-status [--api-url <https://host>] [--json]

Example

observa request-status
Changes locally
Nothing.
Contacts Hosted
Yes
Safety
Only the request’s owner can check it; a request id alone is insufficient. Prints the state and the single next action for it. Before any request exists, there is no saved endpoint to reuse, so it refuses ACCESS_URL_REQUIRED rather than ACCESS_NO_REQUEST — pass --api-url, or run request-access first.

observa pair

Redeem one pairing code and store the Hosted delivery configuration — or, after unpair, re-pair the identity you already have.

Syntax

observa pair --base-url <https://host> (--code-stdin | --code-file <0600-file>)
             [--deployment <id>] [--name <label>]
observa pair          # after unpair: no flags

Example

observa pair --base-url https://governance-plane-observa.tailb473db.ts.net --code-stdin
Changes locally
Atomically writes four owner-only config values: the Hosted base URL, the connector credential, the bound installation id, and the deployment reference.
Contacts Hosted
Yes
Safety
A pairing code is never accepted as a command-line argument — --code is refused outright so it cannot land in shell history or a process list. A --code-file must be owner-only. The credential is stored and never displayed; only the installation id, credential id and fingerprint are printed.

observa unpair

Revoke Hosted delivery for this installation while keeping the installed identity.

Syntax

observa unpair

Example

observa unpair
Changes locally
Stops the service if it is running, then removes the Hosted base URL, connector credential and installation binding from local config, and retains a recovery base URL plus the installation secret so observa pair with no flags can re-pair later.
Contacts Hosted
Yes — it asks Hosted to revoke, and reports how many credentials were revoked.
Safety
The signed installation and its control-plane identity stay intact. Re-pairing needs no new pairing code and creates no new installation.
Different package

The OpenClaw connector’s observa is a different CLI

@mcphersonai/mcpherson-governance-openclaw (0.7.3) ships its own observa executable for the OpenClaw runtime. It is not the package documented above, and its flags are deliberately not the same. Do not mix the two command sets.

Its command set

observa status | agents | agent <id> | activity | decisions
observa pair --api-url <https://host> [--code-file <owner-only-file>]
observa enable | disable
observa killswitch on|off
observa lock on|off
observa credential rotate --new-credential-file <file> --rotation <id>
observa credential recover --new-credential-file <file>
observa unpair | uninstall
observa request-access | request-status

The differences that actually catch people

  • Pairing uses --api-url, not --base-url, and there is no --code-stdin: input is hidden at the terminal, or you pass --code-file.
  • It adds pairing flags the Local Node CLI does not have at all: --deployment-id, --installation-name, --ca-file, --agent-id, --policy-version, --replace-existing, --preflight-only and --rollback <id>. See replacing an existing credential.
  • It has no install, update, rollback, config, diagnose, start, stop, n8n-setup or inspect-workflow. It has enable, disable, killswitch, lock and credential, which the Local Node CLI does not.
  • --profile <name> and --profile-home <dir> select an OpenClaw profile. No command searches other profiles.
  • uninstall does not revoke Hosted credentials. Run unpair first.

Its agents view is real. Unlike the n8n path, the OpenClaw connector resolves a configured agent roster. An agent shown as ACTIVE means a completion receipt in the last five minutes — it does not mean active governance.

Related

Keep going.

Start from the beginning → Access and pairing lifecycle → When a command refuses → What the output does and does not mean →
Start from the beginningTroubleshooting