Hook CLI

The hook binary manages provider webhooks and inspects internal delivery through silicon-hook-client and Hook API v2. Applications own receiving and hide Hook and Ting setup from their users. This CLI stores management sessions and starts no daemon, listener, local gateway, or Ting login.

Build with cargo build -p silicon-hook-cli; the executable is target/debug/hook. Honeycomb manages installation and updates: honeycomb install 'tos>hook'. Maintainers bundle canonical guides with python3 scripts/bundle-cli-docs.py before publishing; CI rejects stale copies.

First session

Obtain an IAM short-lived token for the selected Hook application, then:

hook --profile cos iam --json
hook --profile cos --org tos login <slt>
hook --profile cos login status --json
hook --profile cos --silicon cos:tos create GitHub
hook --profile cos --silicon cos:tos list

hook login <slt> is the short form. --slt-file - reads stdin, and --slt remains available. Prefer a file or stdin when tokens should stay out of shell history and process arguments. Hook does not request passwords, OTPs, or browser callbacks. Login saves access and refresh tokens without configuring receiving, and its response never prints those tokens.

hook iam --json discovers the backend's app_id, iam_url, testing, and login_method before login. With a selected sandbox it discovers that environment's application. It returns no app secret or environment key.

hook login status --json refreshes an expiring session, then checks its current bearer and organization online. It returns authentication state, actor, organization, expiry, profile, and environment. No saved session or a revoked credential reports authenticated: false; service and permission errors fail. An early access-token rejection triggers at most one refresh recovery before the command is dispatched. whoami reads saved metadata without contacting IAM.

Organization selection uses --org, the selected profile/environment setting, then the token's organization. For an unscoped Silicon session, the CLI derives the organization from name:organization and verifies it online. Test sessions never borrow production credentials or organization settings.

Context and saved state

Global flags may appear before or after a command:

SILICON_HOOK_URL and SILICON_HOOK_ORG provide defaults. A profile containing credentials or test selectors stays bound to its original backend; use another profile for a different origin. A signed-in Silicon is the default target. Carbons normally use --silicon; supplying it during login saves the target for that profile or sandbox.

State lives in ${SILICON_HOME:-~}/.silicon-hook/state.json. A nonempty SILICON_HOME selects the base home. hook config home <directory> changes the base to an existing directory; state goes below its .silicon-hook folder. SILICON_HOOK_HOME overrides the complete state directory.

Directories use mode 0700 and files 0600 on Unix. A process lock serializes credential refresh and state updates; replacements are atomic. Before refresh, the CLI durably saves a mutation key and the original attempt time. A lost response is retried with that key, and replacement tokens are saved together. Keep this directory private and do not share one refresh-token family between independent machines.

Command reference

hook <command> --help describes arguments. hook commands lists command paths; hook commands --json includes their complete help. hook docs <topic> reads bundled guides offline.

History limits are 1–10000; a page may contain fewer due to the backend's byte budget. Continue with next_cursor. History and event lookup do not acknowledge anything or change the application's receiving state.

Internal receiving and inspection

An internal owner/admin configures the backend publisher with a newly issued Hook SLT for a dedicated server-owned Silicon. It must be separate from the admin's own management login:

hook --profile admin --org tos --idempotency-key publisher-setup-001 publisher provision --slt-file ./publisher-slt

Use --slt-file - for stdin. This command requires an explicit global --idempotency-key; retry an uncertain result with the same SLT and key. It is organization-scoped and does not require --silicon. The response contains only organization, actor and expiry, not the server's credentials. --replace-rejected explicitly recovers a rejected publisher using a fresh dedicated SLT and new operation key; it cannot replace a usable session. Service setup covers the required permissions and notification type. End users do not perform this setup.

The receiving commands are operator tools for the same setup applications perform internally. They do not start a transport or configure a destination. receiving register acts only for the authenticated recipient. Carbon subscriptions require current IAM visibility of the selected Silicon:

hook --profile reviewer --silicon cos:tos receiving subscribe
hook --profile reviewer --silicon cos:tos receiving status
hook --profile reviewer --silicon cos:tos receiving unsubscribe
hook --profile cos event <event-id>
hook --profile cos publication <event-id>

Subscriptions cover future events, with no historical backfill. Unsubscribing cancels that Carbon's queued observer sends while preserving primary Silicon delivery. A notification already accepted in flight may still arrive; reading the original payload always requires current IAM authorization.

Publication distinguishes pending, accepted_by_ting, and accepted_silently. Its delivery field separates required automation from ordinary notifications; silent records notification visibility. Required muted sends report accepted_by_ting; ordinary muted sends report accepted_silently. Available recipient receipts report destination delivery and read acknowledgments separately. Silent acceptance does not prove a destination received anything, and an acknowledgment does not prove later application processing finished. Applications use the receiving SDK for callback validation, hydration, durable acceptance, and deduplication.

In a selected sandbox, receiving scope and receiving bootstrap expose the scoped inbox/watch setup to an internal runtime. See sandbox commands. They do not enroll a native destination, enable required delivery, acknowledge events or start a listener. Registration reports required_delivery; only the recipient's explicit choice through its enclosing app can enable automation.

Upgrade from the old relay CLI

Before replacing an older CLI that runs a Hook daemon, complete the legacy backlog gate: confirm the old receiver has durably accepted its pending events. Retained v1 events are not automatically copied into Ting. Then use the old executable to run hook daemon stop. Disable any service-manager entry that starts hook daemon run before upgrading. Then install the new CLI through Honeycomb. The new CLI does not kill existing processes or expose a daemon control API.

Existing access/refresh tokens, test selectors, and profile settings remain readable. Obsolete destination, relay-token, stream, and ISI fields are ignored and removed the next time the CLI saves state. Old local relay configuration is not migrated into Ting. The enclosing application's receiving integration owns that setup. webhook, unhook, daemon, listen, deliveries, --isi, and login --webhook-url are no longer accepted.

Signatures and provider secrets

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

Secret files preserve spaces and remove one trailing LF/CRLF. Empty, multiline, control-character, or over-4096-byte secrets fail. Do not supply a secret both inside --signature and through --secret-file. Omitting one at creation generates a secret. set-secret preserves the encoding unless supplied and leaves the URL, policy, and activation state intact; the old secret immediately stops verifying.

Creation, rotation, and environment-key responses may contain secrets; store them only in private files. show does not retrieve an original signing secret. See signature expressions for the algorithms and encodings. All these operations also work in testing.

hook about prints project links. hook report "description" --pr https://github.com/teamofsilicons/silicon-hook/pull/123 explicitly submits an issue through an authenticated GitHub CLI. Telemetry excludes report text.