Command line
Call every Vigilfield API operation from a terminal or a script with vf.
vf is Vigilfield's command-line tool. It runs every API operation, and it manages detection rules as code.
Install
Download the binary for your platform from the releases. There are builds for Windows, macOS and Linux, on x86_64 and arm64. Check the download against SHA256SUMS.
Sign in
vf signs in with a client: a client id and a client secret. For your own terminal, use an agent's client, which acts for you within the scopes you give it. A team's integration uses an app's.
vf login --org <slug> --team <team-id>vf login asks for the client id and secret, checks them, and keeps them in your operating system's keychain: Keychain on macOS, Credential Manager on Windows, the Secret Service on Linux. Where no keychain is available, it refuses, and you use the environment variables below. vf never writes a secret to a file.
<slug> is your organization's address, as in <slug>.vigilfield.com. --team sets the team your calls act as; you can also pass it on any command. vf whoami shows who you are signed in as, and vf logout forgets the client. If you sign in to several organizations, pass --org to choose one.
Environment variables
Set these instead of signing in, for example in CI. They take precedence over vf login.
| Variable | Value |
|---|---|
VF_URL | https://<slug>.vigilfield.com/api/v1 |
VF_TEAM_ID | The team the calls act as |
VF_CLIENT_ID + VF_CLIENT_SECRET | A client's credentials |
VF_CLIENT_ID + VF_OIDC_TOKEN | A federated client and the CI job's OIDC token. See Sign in from CI without a secret |
VF_TOKEN | An access token you already have |
Run any operation
Every API operation is a command, named after its section of the API reference and the operation:
vf alerts list --status open
vf rules get --id rule-0123456789abcdef
vf alerts list --all # every page, as one JSON array- Path and query parameters are flags.
vf <section> <operation> --helplists them. - Send a request body with
--input body.json(or--input -for stdin), or set fields one at a time with--field name=value. A value that is valid JSON is sent as JSON, so--field enabled=falsesends a boolean. - The answer is printed as JSON.
vf api calls any endpoint, including one newer than your copy of vf:
vf api GET /alerts?status=open
vf api PATCH /rules/rule-0123456789abcdef --field enabled=falseExit codes
| Code | Meaning |
|---|---|
0 | Done |
1 | Failed: network, sign-in or server error |
2 | Refused: the request or the rule files were invalid, or conflicted with what exists |