Skip to content

Product Requirements Document — knife

Purpose and scope

This document specifies the requirements for knife, a command-line interface for managing a snackbox instance. It covers the CLI behavior, configuration model, output conventions, and non-functional constraints. It does not cover the snackbox server itself.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Definitions

Term Definition
knife The CLI described by this document
snackbox The headless CMS server that knife communicates with
operator A person who installs and configures knife on a system or in a pipeline
user A person who runs knife interactively to manage a snackbox instance
token A short-lived JWT access token used to authenticate API requests
refresh token A longer-lived token used to obtain a new access token without re-entering credentials

Functional requirements

Authentication

  • knife MUST provide a login command that accepts an email address and password and stores the resulting tokens in the config file.
  • The login command MUST prompt for the password interactively when it is not supplied as a flag, and MUST NOT echo the password to the terminal.
  • knife MUST provide a logout command that invalidates the current session token on the server.
  • knife MUST provide a logout-all command that invalidates all sessions for the authenticated user.
  • The logout-all command MUST prompt for confirmation before proceeding unless the --yes flag is supplied.
  • knife MUST provide a refresh command that exchanges the stored refresh token for a new access/refresh token pair and updates the config file.
  • knife MUST provide a change-password command that prompts for the current password and the new password.

User management

  • knife MUST provide users list, users get, users create, users update, and users delete commands.
  • users list MUST support --page and --limit flags for pagination.
  • users create MUST accept --name, --email, --role, and --password flags.
  • users update MUST accept --name, --email, and --role flags.
  • users delete MUST prompt for confirmation before deleting unless --yes is supplied.
  • The --role flag MUST accept the values admin, author, editor, and member.

Own profile (me)

  • knife MUST provide me get and me update commands that operate on the currently authenticated user's profile.
  • me update MUST accept --name and --email flags.

Settings

  • knife MUST provide settings get and settings update commands.
  • settings update MUST accept flags for every field of the site settings resource: --title, --description, --slogan, --language, --brand-color, --logo-url, --icon-url, --theme, --announcement-text, and --announcement-active.
  • settings update MUST only modify the fields whose flags were explicitly provided; fields that were not specified MUST be preserved.
  • knife MUST provide settings social list, settings social add, and settings social delete commands.
  • settings social add MUST accept --name and --url flags.
  • settings social delete MUST prompt for confirmation before deleting unless --yes is supplied.

Output

  • Every command MUST produce human-readable output by default.
  • List commands MUST render a column-aligned table.
  • Single-record commands MUST render a two-column key/value list.
  • Mutating commands that succeed MUST print a short confirmation message.
  • Every command MUST support a --json global flag that causes the raw API response body to be written to stdout as indented JSON instead of the default format.
  • Error messages MUST be written to stderr.

Configuration

  • knife MUST read configuration from ~/.config/knife/config.yaml, respecting the XDG_CONFIG_HOME environment variable.
  • knife MUST support overriding any config key via an environment variable with the prefix KNIFE_ (e.g. KNIFE_SERVER).
  • knife MUST support a global --server flag that overrides the configured server URL for a single invocation.
  • knife MUST support a global --json flag that overrides output format for a single invocation.

Non-functional requirements

Security

  • Tokens MUST NOT be passed as command-line flags. They MUST be read from the config file only, to prevent leaking them via shell history or process listings.
  • The config file MUST be created with mode 0700 on its parent directory so that it is not readable by other users on the same system.
  • Passwords MUST be read via a terminal prompt that suppresses echo. Accepting a password via flag is OPTIONAL and, when offered, SHOULD be documented as suitable only for non-interactive automation.

Compatibility

  • knife MUST produce a single statically-linked binary with no runtime dependencies.
  • Released binaries MUST target Linux (amd64, arm64), macOS (amd64, arm64), and Windows (amd64).

Statefulness

  • The config file MUST be the only persistent state that knife writes on the user's machine.
  • knife MUST NOT require a running daemon or background service.
  • knife SHOULD be safe to run concurrently from multiple terminals; config writes are best-effort and not required to be atomic.