Skip to content

Administrator guide — knife

System requirements

  • Linux, macOS, or Windows (amd64 or arm64)
  • Network access to the target snackbox instance
  • No runtime dependencies — knife is a single statically-linked binary

Installation

Download the appropriate binary from the release page and place it on the system PATH.

# Linux amd64 example
curl -Lo /usr/local/bin/knife \
  https://gitlab.com/cozybadgerde/applications/knife/-/releases/permalink/latest/downloads/knife_linux_amd64
chmod +x /usr/local/bin/knife

Build from source

Requirements: Go 1.21+, make.

git clone https://gitlab.com/cozybadgerde/applications/knife.git
cd knife
make build
# Binary is written to build/knife

Configuration

Config file location

knife reads and writes configuration from:

~/.config/knife/config.yaml

If XDG_CONFIG_HOME is set, knife uses $XDG_CONFIG_HOME/knife/config.yaml instead. The directory is created with permissions 0700 on first write.

Configuration keys

Key Env var CLI flag Description
server KNIFE_SERVER --server Base URL of the snackbox instance
token — — JWT access token (written by knife login)
refresh_token — — Refresh token (written by knife login)

Tokens are never exposed as flags. They are read from and written to the config file only.

Example config file

server: https://snackbox.example.com
token: eyJhbGci...
refresh_token: eyJhbGci...

Environment variables

All config keys can be overridden with an environment variable by prefixing the key with KNIFE_ and uppercasing it. The only variable typically set in automation is:

export KNIFE_SERVER=https://snackbox.example.com

Flag values on the command line take precedence over environment variables, which take precedence over the config file.

Running knife in CI and automation

For non-interactive environments, supply credentials via flags on knife login and set the server via KNIFE_SERVER:

export KNIFE_SERVER=https://snackbox.example.com
knife login --email ci@example.com --password "$SNACKBOX_PASSWORD"

Storing the password in an environment variable and passing it via --password avoids interactive prompts. Use your CI system's secret store to provide $SNACKBOX_PASSWORD.

After login, the token is stored in the config file for subsequent commands in the same job:

knife users list --json
knife settings update --announcement-text "Deploy in progress"

For pipelines that run knife in a container or ephemeral environment, either re-login at the start of each job or mount a pre-populated config file from a secret.

Using --json for scripting

The --json flag makes knife output the raw API response, which can be piped to jq or other tools:

knife users list --json | jq -r '.[].email'

Upgrading

  1. Download the new binary from the release page.
  2. Replace the existing binary at the same path.
  3. Verify with knife --version.

The config file format is stable across minor releases. If a breaking change is introduced, the release notes will document any required migration.