Your workspace in a file
hookie.yml
project: in the file wins over --project, so a config file is self-describing: you can run it without remembering which project it was for.
What the file can describe
Each kind is matched to what the project has by the field in the Identity column. A kind the file does not mention is left alone.
A destination’s
url and name change in place, so it keeps its id, signing secret and delivery history. An entry under a name the project does not have is taken as a rename of the one destination the file no longer names that has the same URL, and --prune leaves it alone. If you change the name and the URL together, that is a create, so rename in one run and move in the next.
A file describes HTTPS webhook destinations only. A Slack or S3 destination is its credential, a webhook URL or a secret access key, which hookie export leaves out and counts under not_exported. A customer-portal destination belongs to that portal’s customer. apply never compares, updates or prunes any of them: with --prune, or when the file names one, the plan lists it with · as not managed by apply, and diff does not count it as drift. Change those in the console or with hookie destinations update.
version, project and not_exported, which hookie export writes, are accepted too. Any other top-level key is an error that names it, because endpoint: for endpoints: would otherwise be a file that “applies” and does nothing. Sources, WebSocket triggers, ingest keys and portals are not part of the file: they hold credentials. An endpoint’s signature verification is in the file as its scheme and settings (verification: {"scheme": "stripe", "tolerance_seconds": 600}), never its secret. apply never sends or prints a secret, and it refuses a file that holds verification.secret. A new endpoint with a verifying scheme is created without a secret and refuses every request until you set one; apply says so. The same scheme with other settings changes in place and keeps the secret it holds. A different verifying scheme is reported with !, because it needs that provider’s secret: set it with hookie endpoints update --verification.
What apply will and will not do
The admin API is not a reconciler, andapply does not pretend otherwise.
Every field the file states is compared, as canonical JSON. Key order does not matter,
{path, equals: x} and {path, op: "equals", value: x} are the same condition, and a list can be written as a YAML list, inline JSON or a comma string (dataset_filter: orders,shipments). A field the file leaves out is not compared, so a file may say less than the server.
Nothing the file omits is deleted unless you pass
--prune. A config file describes part of a workspace far more often than all of it, and the failure mode of assuming otherwise is deleting a colleague’s endpoint. A resource the file says nothing about is not even read; an explicit endpoints: [] is how you say “there should be none”.apply runs in dependency order: AI agents, record views, rules, endpoints, destinations, workflows, AI triggers, then cron triggers, with deletes last, in reverse. A run stops at the first failure rather than half-applying in scattered order.
Gate CI on drift
hookie diff exits 7 when the project does not match the file: anything to create, update or delete, or a !. It exits 0 when they match. Any other non-zero code is a failed run, not drift. It is 7 rather than terraform’s 2 because 2 already means a usage error here, and a CI job has to be able to tell drift from a broken command.
--json gives the plan as data: each change with its op, kind, the fields that changed and any that are blocked, and a pending count of the changes that are not same:
Start from what a project already has
hookie export [--project X] [--format yaml|json] [-o file] writes a project’s configuration in exactly the format apply and diff read, so hookie export > hookie.yml && hookie diff -f hookie.yml reports no changes. It is how you put an existing project under version control without retyping it.
Nothing secret is in it. Endpoint URLs (they are credentials), signing secrets, ingest keys, and Slack and S3 destinations stay on the server, and the file lists what it left out under not_exported. A destination into one of the project’s own endpoints is written as endpoint: <slug> in place of its URL, which apply resolves in the target project. A destination into any other endpoint is left out. Applying an export to a different project creates fresh URLs and signing secrets there. An AI agent is exported with a ref, its id in the source project, and apply points every workflow agent_call that names that ref at the agent of the same name in the target project, creating it first if need be.
Endpoint slugs are unique across a workspace, not per project. Applying the same file to a second project in the same workspace still gets a
409 for its endpoints. To copy a project’s setup within a workspace, use the console’s Clone project or import, which name the copies {slug}-copy. See Export, import and clone a project.The YAML it reads
Deliberately a subset, and it refuses the rest by name and line rather than guessing:
A parser that quietly mis-reads an anchor sends the wrong configuration to a live workspace, which is strictly worse than one that says it cannot read it.
.json is accepted too, and is the escape hatch for anything this will not parse.
Environment
Profiles
There is no profile flag, becauseHOOKIE_CREDENTIALS already is one. Give each Hookie account its own credential store, and sign in to each once:
Exit codes
6 groups the three cases where retrying the identical command is the reasonable next move, so a script needs one test rather than three.
A destructive command on a non-interactive stdin refuses rather than assuming yes. A CI job that means it passes
--yes; one that did not mean to gets an error instead of a deletion.Credentials on disk
~/.hookie/credentials.json, mode 0600, one entry per origin, written through a temp file and a rename so a crash cannot leave a half-written store. It holds the access token, the refresh token and the OAuth client registration.
hookie logout drops the tokens and keeps the client registration, so reconnecting reuses the same OAuth client instead of adding another row to Settings → Connected agents. hookie logout --all --purge is not a thing; to remove a registration too, delete the file.
The access token is refreshed before it expires, and a refresh shared between concurrent commands is only spent once. If the token endpoint is unreachable you are told that, rather than being told to reconnect — reconnecting needs the same endpoint.