CLI reference

This page is the reference for the hikyaku command line. Read it when you need the flags of a command, or the rules every command shares: the global flags, how spec files are found and merged, and the exit codes.

Everything hikyaku does is a hikyaku subcommand. Each command has a section below, with its flags in a table.

Quick start

The four commands you use first, in this order:

hikyaku init --template webhook-fanout     # scaffold hikyaku.yaml
hikyaku validate                           # check it
hikyaku doctor                             # reach every destination, model and secret
hikyaku run                                # start the relay

Commands

Two more commands help with the shell. hikyaku completion bash|zsh|fish|powershell prints a shell completion script. hikyaku help <command> (or --help on any command) shows that command’s help.

Global flags

Every command takes these flags:

Spec files

Commands that read a spec take it from -f, --file. The default is hikyaku.yaml in the working directory. -f can repeat. A directory means its *.yaml and *.yml files, in name order, without the *.test.yaml files of hikyaku test. The files are merged into one spec, as The spec describes, and every file must agree on name.

hikyaku run

hikyaku run [--watch]

hikyaku run starts the relay: its sources, its delivery workers and the admin API (on :9090 by default). It is the container’s entrypoint.

• It stops on SIGINT or SIGTERM. In-flight messages get server.shutdown_grace (20s by default) to finish.
• It reloads the spec on SIGHUP or POST /reload. A reload that changes genkit: or the model providers starts a new Genkit instance. A reload that changes server.admin.listen moves the admin API. See hot reload.

hikyaku validate

hikyaku validate [--check-secrets]

hikyaku validate loads the spec and checks it without starting anything. It reports:

• unknown keys and wrong types, with file and line;
• dangling references (a name that nothing declares);
• fallback cycles;
• AI candidates that are not destinations;
• hedging without idempotent;
• the protocol matrix (the modes each protocol supports as a source or a destination);
• every CEL expression, jq program and template.

Exit 0 when the spec is valid, 2 with every error otherwise.

Some protocol keys are checked by the protocol’s own module, when the relay builds the source or destination. Kafka brokers written as URLs instead of host:port is one example. hikyaku doctor builds every destination, so it catches a destination’s bad keys before hikyaku run does.

hikyaku lint

hikyaku lint [--strict]

hikyaku lint validates the spec, then warns about settings that work but probably should not:

• an unpinned decision model (its calibration changes between releases);
• an AI router without a router fallback;
• min_margin with multi: true;
• min_confidence: 0, so every answer passes;
• on_low_confidence unset;
• a single-model chain;
• a required destination without a fallback;
• a load-balancing group without health checks;
• dead letters to stdout or stderr;
• no admin token;
• a listen source without auth;
• ack: accepted with the memory buffer;
• a chain whose last router has a when condition;
• a fallback destination that batches;
• an ordered source feeding a destination that batches.

Exit 0 with warnings, 2 when the spec is invalid.

hikyaku graph

hikyaku graph [--format mermaid|dot|json] [--dead-letter]

hikyaku graph draws the spec as a diagram, so you can see where a message may go:

• every source points at the routes that read it;
• every route points at the destinations it may pick: its to, the rules, defaults and candidates of its routers, and the on_invalid of a validate step;
• every destination points at its fallbacks.

A fallback, a shadow destination and an on_invalid destination are dashed lines. A destination that only a later router of the chain can pick is labeled with that router, such as static fallback.

The command reads the spec only. It connects to nothing and reads no secret.

hikyaku graph > relay.mmd                           # a Mermaid flowchart
hikyaku graph --format dot | dot -Tsvg > relay.svg  # with Graphviz

The default output is a Mermaid flowchart. GitHub and many documentation tools render it inside a mermaid code block:

flowchart LR
  s0(["stripe<br/>http"])
  r1{{"payments<br/>rules"}}
  d2["billing<br/>http"]
  d3["spool<br/>file"]
  d4["audit<br/>http"]
  s0 --> r1
  r1 --> d3
  r1 -->|"default"| d2
  r1 -.->|"shadow"| d4
  d2 -.->|"fallback"| d3

Sources are rounded, routes are hexagons, destinations are boxes, and the dead-letter queue is a cylinder.

hikyaku test

hikyaku test [file or directory ...] [--run regexp] [--json]

hikyaku test checks that the spec does what you expect with the messages you give it. A test is a message from a source, and what must happen to it: the destinations it goes to, the body each one gets, the fallback that takes over when a destination is down. Run it before a deploy and in CI, so a change to a filter, a rule or a transform cannot break a route without you knowing.

Nothing is sent. Every destination, every group member and the dead-letter queue is replaced by a stand-in that keeps what it gets. Filters, transforms, routers, retries and fallbacks are the real ones, without their waits: no backoff, no deliver_after, no rate limit. Stores are in memory. Every test runs on a fresh relay, so one test cannot change another.

Without an argument the command reads hikyaku.test.yaml. A directory stands for its *.test.yaml and *.test.yml files.

# hikyaku.test.yaml
tests:
  - name: a payment goes to billing in cents
    source: stripe
    body: { id: p1, type: payment, amount: 12.5 }
    expect:
      status: delivered
      to: [billing]
      shadowed: [audit]
      delivered:
        billing:
          body: { id: p1, cents: 1250 }

  - name: billing down falls back to the spool
    source: stripe
    body: { id: p2, type: payment, amount: 1 }
    down: [billing]
    expect:
      status: delivered
      delivered:
        billing: { via: spool, contains: { id: p2 } }

  - name: a ping is filtered out
    source: stripe
    body: { type: ping }
    expect: { status: filtered, to: [] }

$ hikyaku test
✓ a payment goes to billing in cents (1ms)
✓ billing down falls back to the spool (0s)
✗ a ping is filtered out (0s)
    status: want filtered, got delivered
    to: want [], got [billing]
    route payments: rules → billing, audit
✗ 1 of 3 test(s) failed

A test has these keys:

expect has these keys:

Under delivered, each destination has these keys:

A test sees the message as the destination’s transforms left it. It does not see what the protocol adds after that, such as the url, headers or body template of an http destination, or the subject of an email.

AI routes

A route with an AI router calls its model, as hikyaku route --dry-run does. To test the rest of the spec without a model, answer for the route with decide: at the top of the file for every test, or inside one test.

decide: { triage: [support] }     # every test: the triage route picks support
tests:
  - name: a billing question is sent with its account
    source: chat
    body: { text: "where is my invoice", account: 42 }
    decide: { triage: [billing] } # this test: billing
    expect:
      delivered:
        billing: { contains: { account: 42 } }

Secrets are read only when a test calls a model. A spec whose AI routes are all answered for, or that has none, is tested without any secret or key. To score the model’s own answers on labeled cases, use hikyaku ai test.

Enrich calls

An enrich step makes no request in a test. Give the answer of each call with enrich: at the top of the file for every test, or inside one test. An entry of a test comes before the entries of the file, and the first entry whose url matches answers.

enrich:
  - url: "https://crm.example.com/customers/*"   # * stands for any run of characters
    answer: { tier: free }
tests:
  - name: a gold customer goes to the priority queue
    source: in
    body: { customer_id: c42 }
    enrich:
      - { url: "https://crm.example.com/customers/c42", answer: { tier: gold } }
    expect: { to: [priority] }
  - name: the order is dead-lettered when the CRM is down
    source: in
    body: { customer_id: c7 }
    enrich:
      - { url: "https://crm.example.com/customers/c7", error: status 503 }
    expect: { status: dead_lettered }

A call that no entry answers fails, and the test fails with the method and the URL of the call, so a test never reaches a real server.

Filters that cannot be evaluated

A filter that cannot be evaluated for a message, for example because it reads a key the message does not have, keeps the message. In a test that is a failure: the message got through for a reason the spec does not say. The failure names the route or the destination and gives the error.

When the message is meant to get through that way, set filter_errors: true under expect.

Exit 0 when every test passes, 1 when a test fails or no test ran, 2 when the spec or a test file is invalid.

hikyaku init

hikyaku init [--template NAME] [--dir DIR] [--force]

hikyaku init writes a hikyaku.yaml from a template. The spec validates as written; edit it from there.

hikyaku schema

hikyaku schema [--out FILE]

hikyaku schema prints the JSON Schema of the spec. A JSON Schema describes the keys a file may have and the type of each one. Editors use it to complete and check your YAML, through the # yaml-language-server: $schema=... line; see The spec.

The schema is the same one the docs serve at /schema/hikyaku.schema.json, plus the types and options: of the plugins:

• the types a custom build registers;
• the out-of-process plugins the spec (-f) lists under plugins:. hikyaku starts them to ask for their schema.

hikyaku doctor

hikyaku doctor [--timeout 5s]

hikyaku doctor loads the spec, resolves its secrets through mamori, builds its destinations and checks the setup. It prints one line per check:

✓ spec hikyaku.yaml: 1 sources, 2 destinations, 1 routes
✓ secrets 2 resolved
✓ plugins
✓ destination billing
✓ destination support[0]
✓ destination support[1]
✓ dead_letter
✓ store default (default)
✓ model typesafe/jev-1.13.0

It checks:

• the spec;
• how many secrets resolved (values are never printed);
• that this build has every type the spec uses;
• each destination endpoint and each group member (a member without a name is shown as <group>[i]);
• the dead-letter queue and each fallback of it;
• every store;
• every model of the AI chains and of the model destinations.

Exit 0 when every check passed, 1 when one failed. A spec that does not load or validate counts as a failed check (see exit codes).

hikyaku send

hikyaku send --to billing --data @msg.json --header X-Tenant:acme --content-type application/json

hikyaku send pushes one message to one destination through its full delivery path: transforms, timeout, retries, the circuit breaker (which stops attempts to a destination that keeps failing), the fallback chain and, at the end, the dead-letter queue (DLQ). It prints what each hop did.

• Exit 0: the message was delivered.
• Exit 1: it was not. It was dead-lettered, or a best-effort destination dropped it.
• Exit 3: the DLQ could not take it either.

hikyaku route

hikyaku route --source webhooks --data @msg.json [--subject S] [--attr name=value] [--dry-run] [--json]

hikyaku route takes one message as if it had arrived on --source. It runs the message through every route of that source: filters, transforms, routers and delivery.

With --dry-run, it stops after the routers and prints the decision of each route instead: the router that answered, the model, the probability of each candidate, the destinations chosen, and the fallback hops it would take.

Without --dry-run, it exits 1 when the message was not delivered: dead-lettered, failed or unrouted. A message that every route filtered out exits 0.

hikyaku ai

hikyaku ai groups the tools for AI routes. It has one subcommand, hikyaku ai test.

hikyaku ai test

hikyaku ai test --route smart-triage --cases cases.yaml [--min-accuracy 0.9] [--bins 10] [--json]

hikyaku ai test scores an AI route on labeled cases. A case is one message and the destinations it should reach. The command runs each case through the route’s router, without delivering, and reports:

• the accuracy;
• a confusion matrix (which destinations were chosen for each expected one);
• the calibration, in reliability bins (whether the model’s confidence matches how often it is right);
• the latency.

Use it to tune min_confidence and min_margin. hikyaku history export --labeled turns recorded corrections into such cases. Exit 1 when the accuracy is below --min-accuracy.

Each case has a name, the message as data (JSON) or body (text), and expect, the destinations it should reach. A case may also set the message’s subject, headers and attributes, for routers and when conditions that read them:

cases:
  - name: refund
    data:
      text: I was charged twice this month
      customer_id: c-42
    expect: [billing]
  - name: outage
    body: The dashboard has been down since 9am
    subject: tickets
    headers:
      X-Tier: gold
    attributes:
      channel: email
    expect: [support]

hikyaku chaos

hikyaku chaos --destination billing [--fail 50%] [--latency 2s] [--status 503] [--data @msg.json] [--count 100]

hikyaku chaos wraps one declared destination with the fault injector, locally. You see the retry and fallback policy at work without breaking anything real. It runs in one of two modes:

• With --data, it pushes --count copies of the message (100 by default) through the destination’s retry and fallback path. No source is started. It prints a summary: the attempts per message, how many the destination delivered, how many each fallback delivered, the dead letters, the messages lost (neither delivered nor dead-lettered), and the p50 and p95 latency. It exits 1 when a message was lost.
• Without --data, it runs the relay as hikyaku run does, with the destination wrapped. Real traffic from the sources meets the faults. --count does not apply. Stop it with Ctrl-C.

chaos 100 messages to billing, 163 attempts (1.6 per message)
  delivered by billing     88
  delivered by fallback billing-dr  12
  dead-lettered          0
  lost                   0
  latency p50 212ms  p95 1.4s

hikyaku dev

genkit start -- hikyaku dev

hikyaku dev runs the relay like hikyaku run, and also starts the Genkit reflection server. Run it under genkit start to get the Genkit Developer UI. The UI shows every AI route as a route/<name> flow, with a trace of each decision, and can run a flow on a message of your own. From a clone of the repository, make genkit-ui does this for the ai-triage example on a fake model.

hikyaku tail

hikyaku tail [--source webhooks] [--admin http://localhost:9090]

hikyaku tail streams the envelopes of a running relay as they arrive. It reads them from the /v1/tail endpoint of the relay’s admin API. For each message it prints two lines:

• one when the message arrives: time, source, ID, subject and the start of the body;
• one when it is finished: time, source, ID and its status, which is delivered, dead_lettered, unrouted, filtered or failed.

With --json, it prints each event as a JSON line instead.

hikyaku forward

hikyaku forward --to http://localhost:3000/webhooks [--source stripe] [--admin https://relay.example.com:9090]

hikyaku forward sends a copy of every message a running relay receives to a URL on your machine. Use it to work on a webhook handler with real traffic, without a public URL for your laptop: the sender keeps calling the relay, and your local server gets the same requests.

It reads the relay’s live stream over the admin API, like hikyaku tail, and makes one request per message. The request has the method, the headers and the body the message came with, so a signature header such as Stripe-Signature still matches the body. It also has X-Hikyaku-Id and X-Hikyaku-Source. A message from a source that is not http is sent with POST.

$ hikyaku forward --to http://localhost:3000/webhooks/stripe --source stripe
✓ forwarding http://127.0.0.1:9090 to http://localhost:3000/webhooks/stripe
10:42:07.113 stripe evt_1PqX → 200 (12ms)
10:42:09.540 stripe evt_1PqY → 500 (3ms)

The relay delivers every message as usual. What your local server answers is printed and changes nothing on the relay.

It is a tool for development, so it does not promise delivery:

• a message that arrives while the connection to the relay is down is not forwarded later. When the stream ends, the command connects again by itself;
• a relay under heavy load may skip events for a slow reader, as it does for hikyaku tail;
• a secret value of the spec that appears inside a message is hidden, as in hikyaku tail;
• the headers a source removes after it checks them, such as a bearer token, are not there.

The stream needs the admin token from another host, so set server.admin.token on the relay. Anyone with that token can read every message, so treat it like a password.

hikyaku dlq

hikyaku dlq works on the dead-letter queue of the spec, when it is a file DLQ (dead_letter.type: file). It works offline: it reads the file directly, without a running relay. Its subcommands are hikyaku dlq list, hikyaku dlq inspect and hikyaku dlq replay.

hikyaku dlq list

hikyaku dlq list [--since 1h] [--json]

hikyaku dlq list lists the dead letters, one line each: ID, time, the destination that failed (or route <name> when routing failed), the reason (delivery, no_route, transform or schema), the attempts and the last error.

hikyaku dlq inspect

hikyaku dlq inspect <id>

hikyaku dlq inspect prints one dead letter in full, as JSON: the envelope, its dlq attribute (route, destination, reason, attempts, the last error and every hop with its outcome) and, when an AI router decided, ai.decision.

hikyaku dlq replay

hikyaku dlq replay [--to billing-dr] [--since 1h] [--id ID] [--dry-run]

hikyaku dlq replay sends dead letters again. Each one keeps its original ID as its idempotency key, so a destination that already has the message can drop the duplicate.

• A dead letter goes to the destination that failed, or to --to when it is set, through that destination’s full retry and fallback path.
• A routing failure (reason no_route, transform or schema) without --to runs through its route again.
• A message that fails again is dead-lettered again.

Exit 1 when any replay did not go through.

hikyaku history

hikyaku history reads and edits the routing history of a running relay. It goes through the relay’s admin API, so it works the same with the memory store and the Redis store. Every subcommand takes --admin URL (the admin API) and --token (the admin token, server.admin.token). Its subcommands are hikyaku history show, hikyaku history correct, hikyaku history export and hikyaku history forget.

hikyaku history show

hikyaku history show --route smart-triage --key c-42

hikyaku history show prints the stored past calls of a key, exactly as the model will see them.

hikyaku history correct

hikyaku history correct <msg_id> --to billing [--note "refund, not a bug"]

hikyaku history correct records a correction for a past message: where it should have gone. Later calls for the same key see the correction in their history (the feedback loop).

hikyaku history export

hikyaku history export [--since 30d] [--route smart-triage] > history.ndjson
hikyaku history export --labeled [--since 30d] [--route smart-triage] > cases.yaml

hikyaku history export writes the recorded calls as NDJSON, one call record per line. With --labeled, it writes only the corrected calls instead, as a YAML cases file for hikyaku ai test. Each case is labeled with its correct destinations.

hikyaku history forget

hikyaku history forget --route smart-triage --key c-42

hikyaku history forget deletes the history of a key, for right-to-be-forgotten requests.

hikyaku version

hikyaku version [--json]

hikyaku version prints the version, the commit and the build date, the Genkit version the binary was built with, and the Go version and platform.

Shell completion

hikyaku completion bash|zsh|fish|powershell

Prints the completion script for a shell. The Linux packages install the bash, zsh and fish scripts; Install shows how to load them by hand.

Exit codes

Exit 1 means one of these:

• a lint warning under --strict;
• a doctor check, including a spec that does not load;
• an ai test below --min-accuracy;
• a send that did not deliver its message;
• a route whose message was dead-lettered, failed or unrouted;
• a chaos --data run that lost a message;
• a dlq replay that did not go through.

Errors and redaction

Errors go to stderr. Every secret value resolved through mamori is redacted from errors, logs and output. It never appears in /debug either. See Security.