Hook CLI#

hook manages a Silicon's signed provider webhooks: the URLs providers call, their signature policies, the request history, and who else may see or change them. It is built only on silicon-hook-client and speaks Hook API v3. It starts no daemon or listener; delivery to Silicons goes through Ting, set up by the app that hosts the Silicon.

Install#

silicon-apps install hook

Silicon Apps installs the prebuilt CLI and keeps it updated; hook never replaces itself. Development releases install as silicon-apps install 'hook>dev'. Linux (x86_64, aarch64) is available today; on macOS and Windows, until Silicon Apps serves those packages, build from source: cargo install --path crates/cli --locked (binary hook).

First session#

A Silicon:

hook accounts --json                                        # what signing in needs; works offline
silicon-accounts login --app hook -q | hook login --slt-stdin
hook login status --json
hook create GitHub                                          # give GitHub the endpoint_url
hook list
hook events

A Carbon looking after Silicons:

hook login                                  # approve the printed code in a browser
hook silicons                               # the Silicons you look after or were granted
hook --silicon si:scout list
hook config set silicon si:scout            # save a default Silicon

Sign in to Hook explains both sign-ins, the saved session and who can do what.

Output, errors and exit codes#

Results print as JSON on stdout. Hints about the next step go to stderr; --json silences them and prints errors as JSON on stderr:

{"error": {"code": "forbidden", "message": "The actor is not authorized for this action.", "hint": "…", "status": 403, "request_id": "…", "exit_code": 3}}

code is stable: Hook's own refusal codes (forbidden, not_found, delivery_disabled, session_ended…), the sign-in codes from Silicon Accounts (invalid_grant, access_denied, expired_token…), and the CLI's own (not_signed_in, signed_in_elsewhere, refresh_interrupted, previous_version_session, state_unreadable, invalid_input). Exit codes: 0 success, 1 failure, 2 invalid input, 3 sign-in required or refused, 4 not found, 5 conflict, 6 rate limited, 130 interrupted.

Choosing the Silicon#

Hook commands act on one Silicon's hooks. The CLI uses, in order: --silicon (a si: id or the Silicon's uuid), the profile's hook config set silicon, and for a signed-in Silicon its own uuid. A Carbon without either gets an error that names hook silicons.

Global flags#

Plain http is accepted only for this machine (localhost or a loopback address), for a local Hook and Silicon Accounts.

Commands#

hook <command> --help explains each command, how it combines with others and its flags. hook commands lists every path; hook commands --json adds the full help of each. hook docs <topic> reads these guides offline.

History limits are 1 to 10,000; a page may hold fewer because of a byte budget. Continue with next_cursor. Reading history never acknowledges anything.

Signatures and provider secrets#

hook create GitHub --signature @github-policy.json
hook create Stripe --signature @stripe-policy.json --secret-file stripe-secret.txt
hook create LocalDemo --unsigned
hook set-secret <id> --secret-file encoded-secret.txt --secret-encoding hex
hook update <id> --patch '{"description": null}'

Secret files keep spaces and lose one trailing line ending; empty, multi-line, control-character or over-4096-byte secrets are refused. Do not give a secret both inside --signature and with --secret-file. Without one, creation generates a secret and prints it once. set-secret keeps the encoding unless you pass one, and the previous secret stops verifying at once. Signature expressions lists the algorithms and encodings.

A Silicon's own Silicon Accounts events#

Silicon Accounts can tell a Silicon when it is signed out, renamed or given a new custodian, by calling a webhook. Point it at a Hook hook:

hook connect-accounts                         # prints the hook URL and the command to run
silicon-accounts webhook set <url>            # as the Silicon; prints a whsec_ secret once
silicon-accounts silicon webhook set si:scout <url>   # or as its custodian
hook connect-accounts --secret-file -         # paste the whsec_ secret

Until the secret is stored, Silicon Accounts deliveries are withheld as unverified (hook blocked shows them).

Delivery through Ting#

When the Hook server delivers through Ting, each verified request reaches the Silicon as a compact reference that its app hydrates with the receiving SDK. receiving register enrols you with Ting; a Carbon with access can receiving subscribe to a Silicon's future events. When the server has no Ting, Hook still receives and stores every event, these commands answer delivery_disabled, and publication says delivery_disabled: read events with hook events.

State, settings and telemetry#

State lives in ${SILICON_HOME:-~}/.silicon-hook/profiles.json (0600, directory 0700). SILICON_HOOK_HOME names the exact directory; hook config home <dir> moves the base to an existing directory. Writes are atomic and serialized by a lock file.

Telemetry is on by default and carries no payloads or credentials: one event per command (name, outcome, duration), sent to Hook only while signed in. Turn it off with hook config set telemetry off or SILICON_HOOK_TELEMETRY=off. See telemetry.

Upgrading from Hook before 1.0#

• Sign in again: hook login (Carbons) or the Silicon command above. The old state.json is left untouched and never read for credentials; its URL, default Silicon and telemetry choice carry over.
• Hooks belong to Silicons: choose one with --silicon. Flags and commands of earlier versions that no longer apply (test environments, publisher setup, separate Ting approval) are gone; the old global flags fail with an explanation of what replaced them.
• New: hook login without arguments (device flow), --slt-stdin, accounts --json, silicons, access, allow-list, connect-accounts.

hook report "what happened" --pr https://github.com/teamofsilicons/silicon-hook/pull/123 files a bug through your authenticated GitHub CLI. Only your text, the optional pull request and the version are sent.