API tokens

Sign in normally, then open Profile → Settings → API tokens. Choose a connected source, a name, read or write access, and an expiry. Copy the token once and keep it in your tool’s secret or environment configuration.

Tokens work with both GitHub and SQLite sources. Each token grants exactly one source, including its Git branch and board folder. It cannot discover other sources, change source settings or issue more tokens. The account can hold up to 20 active tokens; an expiry must be between 1 and 90 days.

Use Revoke in Settings to disable a token immediately, including any signed session derived from it. Signing out of the browser ends that browser session; tool tokens stay valid until revoked or expired. API tokens are stored as SHA-256 hashes. Their plaintext is returned only at creation and is never saved in browser storage.

Keep authorization on persistent storage

The account backend stores token metadata and encrypted GitHub credentials in FOLIO_BOARD_AUTH_DB. If it is unset, the file is <workdir>/.auth/security.sqlite3. Put it on persistent storage alongside the SQLite boards. Restrict this directory to the service account and preserve FOLIO_BOARD_SESSION_KEY across deployments.

Provider credentials use AES-256-GCM with a key derived from the signing key. Git origins contain no credential. Fetch, clone and push receive a transient authentication header through Git’s process environment, with credential helpers disabled; the header is never written to the clone’s configuration. Back up that key separately from the databases. Starting with a different key fails instead of silently losing access to the encrypted credentials.

GitHub tokens use the signed-in person’s access, never the deployment owner’s credential. Repository membership is checked on every request. An expiring GitHub user token is refreshed when the App supplies a refresh token; tool and browser handles share the refreshed credential. Without refresh support, a GitHub API token cannot outlive that user credential. Reconnect and issue a new token if GitHub revokes the connection or its refresh credential expires.

SQLite tokens retain the stable signed-in identity and recheck the database’s reader/writer policy. GitHub token expiration does not disable a SQLite token.

Use the remote CLI

Install the network binary from the same checkout as the backend:

cargo install --path crates/folio-board-server --bin folio-board --locked

Set FOLIO_BOARD_API to the API origin and FOLIO_BOARD_TOKEN through your shell or secret manager. The CLI does not accept a secret in an argument or URL.

export FOLIO_BOARD_API=https://board.example.com
folio-board health
folio-board board
folio-board card improve-search
folio-board move improve-search in-progress
folio-board update improve-search --set priority=high
folio-board comment improve-search "The new layout is ready."
folio-board trail improve-search "Implemented the layout" --ref abc1234
folio-board description improve-search --file description.md
folio-board create improve-search --file card.md

move, update and description read the current card hash, then send one guarded write. A concurrent change returns a conflict; the CLI does not retry by overwriting it. Append operations use the service’s append contract. folio-board apply --file request.json sends a complete operation request, including an explicit hash or dry_run flag.

folio-agents board remains the filesystem CLI. Board skills continue to edit Markdown/Git through that CLI; they do not open SQLite databases directly. The network CLI and MCP endpoint use the same API and domain service as browser edits.