User guide — knife
Prerequisites
- A running snackbox instance reachable over HTTP or HTTPS
- An account on that instance with sufficient privileges for the operations you want to perform
Installation
Download the pre-built binary for your platform from the release page.
# Example for Linux amd64
curl -Lo knife https://gitlab.com/cozybadgerde/applications/knife/-/releases/permalink/latest/downloads/knife_linux_amd64
chmod +x knife
sudo mv knife /usr/local/bin/knife
Verify the installation:
knife --version
First-time setup
Run login with the --server flag pointing at your snackbox instance:
knife --server https://snackbox.example.com login
You will be prompted for your email address and password. The password prompt does not echo characters. After a successful login, the server URL and tokens are saved to ~/.config/knife/config.yaml so you do not need to supply --server again.
Command reference
Global flags
These flags can be used with any command.
| Flag | Description |
|---|---|
--server URL | Override the snackbox server URL for this invocation |
--json | Output the raw API response as indented JSON |
--version | Print the knife version and exit |
--help | Show help for a command |
Authentication
knife login
Prompt for credentials and save tokens to the config file.
knife login
knife login --email admin@example.com
Flags:
| Flag | Description |
|---|---|
--email EMAIL | Email address (prompted if omitted) |
--password PASS | Password (prompted securely if omitted) |
knife logout
Invalidate the current session token.
knife logout
knife logout-all
Invalidate all sessions for your account. Prompts for confirmation.
knife logout-all
knife logout-all --yes
Flags:
| Flag | Description |
|---|---|
--yes, -y | Skip confirmation prompt |
knife refresh
Exchange the stored refresh token for a new access/refresh token pair and update the config file.
knife refresh
knife change-password
Change your password. You will be prompted for your current password and then for the new password twice.
knife change-password
Users
knife users list
List all users. Results are paginated.
knife users list
knife users list --page 2 --limit 50
knife users list --json
Flags:
| Flag | Default | Description |
|---|---|---|
--page N | 1 | Page number |
--limit N | 20 | Items per page |
knife users get <id>
Show details for a single user.
knife users get 42
knife users get 42 --json
knife users create
Create a new user.
knife users create \
--name "Alice" \
--email alice@example.com \
--role editor \
--password s3cr3t
Flags:
| Flag | Description |
|---|---|
--name NAME | Display name |
--email EMAIL | Email address |
--role ROLE | Role: admin, author, editor, member |
--password PASS | Initial password |
knife users update <id>
Update an existing user. Only the flags you supply are changed.
knife users update 42 --role admin
knife users update 42 --name "Alice Smith" --email alice.smith@example.com
Flags: same as users create, except --password is not available.
knife users delete <id>
Delete a user. Prompts for confirmation unless --yes is passed.
knife users delete 42
knife users delete 42 --yes
Flags:
| Flag | Description |
|---|---|
--yes, -y | Skip confirmation prompt |
Me (own profile)
knife me get
Show your own profile.
knife me get
knife me get --json
knife me update
Update your own profile.
knife me update --name "Bob"
knife me update --email bob@example.com
Flags:
| Flag | Description |
|---|---|
--name NAME | Display name |
--email EMAIL | Email address |
Settings
knife settings get
Show the current site settings.
knife settings get
knife settings get --json
knife settings update
Update site settings. Only the flags you supply are changed; all other fields are preserved.
knife settings update --title "My Blog" --slogan "Words matter"
knife settings update --announcement-text "We are back!" --announcement-active
knife settings update --language en --brand-color "#3c8dff"
Flags:
| Flag | Description |
|---|---|
--title T | Site title |
--description D | Site description |
--slogan S | Site slogan |
--language L | Language tag (BCP 47, e.g. en) |
--brand-color C | Brand color (CSS hex, e.g. #ff0000) |
--logo-url U | Logo image URL |
--icon-url U | Icon/favicon URL |
--theme T | Theme identifier |
--announcement-text T | Announcement banner text |
--announcement-active | Show the announcement banner |
knife settings social list
List configured social accounts.
knife settings social list
knife settings social list --json
knife settings social add
Add a social account.
knife settings social add --name GitHub --url https://github.com/cozybadgerde
Flags:
| Flag | Description |
|---|---|
--name NAME | Platform name (e.g. GitHub) |
--url URL | Profile URL |
knife settings social delete <id>
Delete a social account by its numeric ID. Prompts for confirmation.
knife settings social delete 3
knife settings social delete 3 --yes
Flags:
| Flag | Description |
|---|---|
--yes, -y | Skip confirmation prompt |
Output formats
By default, knife renders human-readable output:
- List commands produce a column-aligned table.
- Single-record commands produce a two-column key/value list.
- Mutating commands print a short confirmation message.
Add --json to any command to receive the raw API response as indented JSON, which is suitable for parsing with tools like jq.
knife users list --json | jq '.[].email'
knife settings get --json | jq '.title'
Shell completion
Cobra generates completion scripts for bash, zsh, fish, and PowerShell.
# bash (add to ~/.bashrc)
knife completion bash >> ~/.bashrc
# zsh (add to ~/.zshrc)
knife completion zsh >> ~/.zshrc
# fish
knife completion fish > ~/.config/fish/completions/knife.fish
# PowerShell
knife completion powershell >> $PROFILE
Reload your shell after adding the completion script.