CLI operations

Use this page after CLI getting started is working and you want to run the CLI as a regular worker.

Command Model

The CLI polls one or more inboxes and runs one local command for each inbox item.

The main commands are:

• sigvane config init
• sigvane config check
• sigvane inbox poll
• sigvane inbox poll --once
• sigvane inbox poll <inbox-slug>
• sigvane state reset <inbox-slug>
• sigvane version

Run sigvane --help or sigvane inbox poll --help for the current flag list.

Config Discovery

Commands that read config use this order:

1. The command flag, such as sigvane inbox poll --config ./sigvane.yaml or sigvane config check --path ./sigvane.yaml.
2. The SIGVANE_CONFIG environment variable.
3. ./sigvane.yaml in the current directory.
4. The default config path: $XDG_CONFIG_HOME/sigvane/config.yaml, or ~/.config/sigvane/config.yaml when XDG_CONFIG_HOME is not set.

sigvane config init writes to --path when you pass one. Without --path, it writes to the default config path and refuses to overwrite an existing file.

Config Shape

A small config looks like this:

version: 1

server:
  url: https://api.sigvane.com
  api_key: ${SIGVANE_API_KEY}
  poll_interval: 5s
  shutdown_grace_period: 30s

handlers:
  - inbox: github-repo
    command: ["/bin/sh", "-c", "cat"]
    stdin: full_item

Use the inbox slug in handlers[].inbox.

server.api_key can be a literal API key or an environment variable reference such as ${SIGVANE_API_KEY}. Environment variable references are supported for server.api_key.

Each handler command is an argument list. The first entry is the program to run, and the remaining entries are its arguments.

Stdin Modes

stdin controls what the CLI sends to the handler:

• full_item: sends the full inbox item JSON.
• body: sends the decoded request body bytes from the inbox item.
• none: sends no stdin.

full_item is the best default because it gives your command the delivery body plus Sigvane metadata such as the inbox item id, recorded time, headers, and providerDeliveryId.

Polling One Inbox

With no inbox argument, the CLI polls every handler in the config:

sigvane inbox poll

To poll only one configured inbox, pass its slug:

sigvane inbox poll github-repo

Use --once for a one-time drain:

sigvane inbox poll github-repo --once

Continuous polling is the normal worker mode. Run it in the foreground under your service manager or container supervisor.

State File

The CLI saves progress in a state file so it can resume after a restart.

By default, the state file lives at:

~/.local/state/sigvane/state.json

If XDG_STATE_HOME is set, the default is:

$XDG_STATE_HOME/sigvane/state.json

You can override the state path for polling and state reset commands:

sigvane inbox poll --state ./sigvane-state.json
sigvane state reset github-repo --state ./sigvane-state.json

The state file records the resolved inbox id and the last successfully handled inbox item id for each inbox slug.

Handler Failures And Replay

After a handler exits successfully, the CLI saves that inbox item’s id in the state file.

If a handler exits with a non-zero status, the CLI does not advance the saved cursor for that item. The same item can be read again on a later poll.

This gives the CLI at-least-once behavior. Make each handler safe to run more than once for the same providerDeliveryId.

Reset A Saved Cursor

Use state reset when you intentionally want one inbox to start again without its saved cursor:

sigvane state reset github-repo

The next poll for that inbox starts from the oldest retained inbox item that Sigvane still has.

Resetting state does not delete inbox items from Sigvane. It only changes the local CLI worker’s saved progress.

Inboxes Recreated With The Same Slug

The state file stores the resolved inbox id as well as the slug.

If an inbox is deleted and recreated with the same slug, the CLI refuses to poll until you reset the state for that slug. This prevents an accidental replay against a different inbox.

Shutdown

The CLI handles SIGINT and SIGTERM.

When shutdown starts, the CLI gives the currently running handler up to server.shutdown_grace_period to exit. The default is 30s.