CLI getting started

The Sigvane CLI lets your workflow consume and process inbox items.

It polls a Sigvane inbox and runs a command on your machine for each item it finds. That command can be a shell script, a worker, an agent entrypoint, or another automation workflow you control.

This guide starts with the smallest useful setup: print each webhook event from your inbox in the terminal so you can see the flow working end to end.

Before You Begin

You’ll need:

• a Sigvane inbox that is already receiving GitHub events
• the inbox slug, such as github-repo
• a Sigvane API key
• a terminal on the machine where you want the CLI to run

If GitHub is not connected yet, start with Connect GitHub.

1. Install The CLI

1. Open the Sigvane CLI releases page.
2. Download the archive for your operating system and CPU architecture.
3. Unpack the archive.
4. Install the binary as ~/.local/bin/sigvane.

From the unpacked archive directory, run:

mkdir -p ~/.local/bin
install sigvane ~/.local/bin/sigvane

If ~/.local/bin is not already on your PATH, add it before continuing.

Check that the CLI runs:

sigvane version

Prefer to build the CLI yourself? See Build from source, then come back to this guide.

2. Create The CLI Config

Generate a starter config:

sigvane config init

The CLI writes the config to:

~/.config/sigvane/config.yaml

Open that file and set the inbox slug to your Sigvane inbox. For this first test, the finished config should look close to 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

Replace github-repo with your inbox slug.

The command setting is an argument list for the process the CLI runs. The stdin: full_item setting tells the CLI to send the full inbox item JSON to that command. For this first test, /bin/sh -c "cat" prints each webhook event from the inbox to the console.

3. Set Your API Key

Export your Sigvane API key in the same shell:

export SIGVANE_API_KEY='replace-me'

Treat this key like a password. Do not commit it to your repository.

4. Check The Config

Ask the CLI to validate the config before polling:

sigvane config check

You should see:

config ok: ~/.config/sigvane/config.yaml

If the check fails, fix the reported setting and run sigvane config check again.

5. Poll Once

Run one polling pass:

sigvane inbox poll --once

If the inbox has items, the CLI runs the configured command once for each item and prints the webhook event JSON in your terminal.

If nothing prints, trigger a new GitHub delivery or redeliver a recent one from GitHub, then run sigvane inbox poll --once again.

6. Keep Polling

After the one-time poll works, start the CLI without --once:

sigvane inbox poll

The CLI keeps running in the foreground until you stop it.

For a long-running worker, run this same foreground command under a service manager such as systemd or a container supervisor.

See CLI operations for state files, config discovery, and handler behavior.

Use A Project Config

If you want the config in your project directory instead of the default location, pass a path:

sigvane config init --path ./sigvane.yaml
sigvane config check --path ./sigvane.yaml
sigvane inbox poll --config ./sigvane.yaml --once

Handle Duplicates

Your command may see the same provider delivery more than once. This is normal for webhook systems.

Before your command comments on pull requests, deploys code, or changes another system, make it safe to run twice for the same delivery.