Read a Forge's collaboration state

tovio forge — proposals, checks, locks, webhooks, roster, and served policy.

Written By Dustin

Last updated About 3 hours ago

tovio forge is a client that talks to a running Forge over pinned TLS. It never touches the server's storage directly — every write is routed through the running server, which is what keeps writes serialized.

Every subcommand takes --remote <host:port>, and an optional --cert that defaults to this repository's .tovio/relay-cert.der. Add the global --json for a machine-readable shape.

Reads

These return collaboration metadata rather than content — public keys, attribute names, ids, states, and timestamps — so none of them needs an admin role.

They are not unauthenticated, though. On a Forge whose connection ACL is enabled they are member-gated, and a non-member gets TVO-FORGE-004. That is intentional: holder identities, locked paths, and the declared protected paths are exactly the reconnaissance an operator turns the ACL on to withhold.

tovio forge proposal list --target main --remote <host:port>

tovio forge check list --proposal prop:<id> --remote <host:port>

tovio forge lock list --remote <host:port>

tovio forge webhook list --remote <host:port>

tovio forge user list --remote <host:port>

tovio forge policy show --remote <host:port>

Command	What it shows
`proposal list`	Each proposal targeting a lane: id, change id, state, version.
`check list`	Every check against a proposal: name, status, detail, attester, version.
`lock list`	Every active lock: path, holder, kind, TTL window. The authoritative view.
`webhook list`	Subscriptions: id, owner, target URL, active flag, version.
`user list`	The access roster: each member, whether they hold admin, and their attribute claims.
`policy show`	The served manifest: version, path-to-policy declarations, protected lanes.

Posting a check result

tovio forge check post --proposal prop:<id> --name ci/build --status success --remote <host:port>

tovio forge check post --proposal prop:<id> --name ci/build --status failure --detail <run-url> --remote <host:port>

This is the CI post-back surface. Results are keyed by proposal and check name, so re-posting the same name updates it. Only success satisfies a required check; pending and failure both block landing, and a required check that was never posted resolves to pending — which is why TVO-FORGE-003 can fire on a check nobody ran.

The attester is your authenticated principal, never a body field. Keep --detail to a run URL or a short line: it is stored and displayed, so it must not carry plaintext or key material.

Administrative writes

These are signed and gated server-side. A caller without the role gets a clean 403 and nothing changes.

tovio forge lock break <path> --remote <host:port>

tovio forge webhook delete <id> --remote <host:port>

tovio forge proposal ready prop:<id> --required <did> --remote <host:port>

proposal ready promotes an open proposal to approved after its named reviewers have approved. It cannot bypass anything — the Forge re-runs the required-reviewer, protected-path clearance, and current-revision gates, and CI requirements stay enforced by their own surface.

Roster mutations (forge user grant and revoke) are stricter still: owner-only, because minting a signed attribute claim is Key Authority work, not merely administrative.

What never crosses the wire

No plaintext, and no key bytes. A webhook's HMAC secret is stored and shown as a keychain reference. Policy expressions are attribute names, which is why policy show can be an open read at all.