CLI setup and authentication

The browser app needs no installation. This guide is for people who need the optional command-line client and already have authorized workspace access.

Install the pilot archive

The package is named @witnessops/cli and remains private. There is no public npm install command. For an assisted pilot, the operator supplies a versioned .tgz archive and its expected SHA-256 value through the trusted pilot channel. Do not use an archive or checksum copied from an untrusted message.

Install Node.js 22 through your usual trusted package source. From the directory containing the supplied archive and checksum sidecar, verify and install it:

sha256sum --check witnessops-cli-0.0.1.tgz.sha256
npm install --global ./witnessops-cli-0.0.1.tgz
wops auth status

Before login, the final command reports Not signed in. The checksum detects changed bytes only when you obtained the expected value through a trusted channel; it is not a publisher signature. The archive installs only the CLI. A server check also needs the separately supplied, root-owned Local Audit runtime and explicit authorization. If either prerequisite was not supplied, ask the pilot operator instead of cloning an arbitrary source revision.

Sign in

Run as your normal user, not with sudo:

wops auth login

The CLI opens the browser authorization page and prints a code. If the browser cannot open, use the displayed address in your browser. Sign in, enter the code from your own terminal, and confirm the workspace and role. Authorize only a sign-in you started; never enter a code someone sends you.

Return to the terminal and wait for confirmation. Login grants session identity/status and sign-out by default. It does not grant uploads, signing authority or server checks. Owners and Contributors may explicitly request additional server-check rights in the authorization screen; collection still needs its own approved scope and window.

Confirm your session

wops auth status

Check the account, workspace, role and active session. If current status cannot be confirmed, restore connectivity and retry. A local credential file alone does not establish current access. Do not copy or share that file.

Sign out

wops auth logout

This removes the local credential and attempts server revocation. If revocation cannot be confirmed, the CLI says so; do not describe that as confirmed server sign-out.

Common problems

• No workspace or access paused: verify your email and create your workspace, or accept an Owner’s invitation. For paused or unexpectedly restricted access, contact Support.
• A local session already exists: check status or log out before starting another login.
• Code expired or login declined: start login again from your own terminal.
• No browser on the Linux machine: open the displayed authorization address on your browser-equipped device and enter your own terminal code.
• Server unreachable: check connectivity. Do not paste tokens into chat or change servers to bypass access rules.

Return to Get started to find assets, observations and reports. Authenticating the CLI is not a server check and does not collect evidence.