stoke

CLI for the heavy-duty forge (Forgejo). Named for feeding a fire — the operator’s hand on the forge.

stoke turns real forge work into commands: auth, repos, issues, PRs, releases, labels, orgs, and a raw API escape hatch. Default instance: https://forgejo.heavyduty.builders.

Built with Commander.js. Node.js ≥ 22.12 required.

---

Install

Debian / Ubuntu (recommended)

curl -fsSL https://forgejo.heavyduty.builders/heavy-duty/stoke/raw/branch/main/scripts/install-apt.sh | bash

That script adds the forge’s Debian registry, bootstraps Node 22 when the distro package is too old, and installs stoke. Upgrades then come with apt-get upgrade.

From source

npm install && npm link
# or: node src/cli.js <command>

Notes

• On some apt versions (sqv / Debian 13+), Forgejo’s registry signature is rejected (upstream bug). The installer falls back to [trusted=yes] over HTTPS; once the forge signature is fixed, the signed source is preferred again.
• Each release also attaches a .deb for sudo dpkg -i stoke_<version>_all.deb.

---

Quick start

stoke auth login          # interactive; or use STOKE_USERNAME / STOKE_PASSWORD
stoke auth status
stoke issue list -o heavy-duty -r stoke
stoke pr review -o heavy-duty -r stoke -n 3 --event approve -b "LGTM"

Full options and examples for every command: docs/COMMANDS.md.

---

What you can do

Area	Commands
Auth	login, logout, status
Repos	clone, create, list, import, import-batch, rename, transfer
Issues	list, create, show, comment
PRs	list, create, show, comment, review, merge
Releases	list, view, create
Labels	list, create, delete, add, remove
Branches	list
Collaborators	add
Orgs / teams	create, repos, avatar, team list/create/members
Users	list, show
Escape hatch	stoke api <endpoint> — any Forgejo REST path with the stored token

Read commands support --json for machine-readable API output (see COMMANDS.md).

---

Configuration

Default path	~/.config/stoke/config.json (or $XDG_CONFIG_HOME/stoke/config.json)
Override	--config <path> (before the subcommand) or STOKE_CONFIG_FILE
Permissions	directory 0700, file 0600

Stored fields: url, login, username, email, token, tokenId.

Token scopes — auth login mints a least-privilege token by default (issue R/W, repository R/W, user R, organization R). Use --full-scopes or --scopes <csv> for org admin / package publish. Details in COMMANDS.md → Auth.

Environment

Variable	Purpose
STOKE_URL	Default Forgejo base URL
STOKE_USERNAME / STOKE_PASSWORD	Defaults for auth login
STOKE_CONFIG_FILE / STOKE_CONFIG_DIR	Config location
XDG_CONFIG_HOME	Default config directory parent
GITHUB_TOKEN	Source token for repo import when --github-token is omitted

FORGEJO_* names still work as fallbacks.

---

Develop

src/cli.js      commands and I/O
src/api.js      Forgejo client (Basic auth for tokens; token auth elsewhere)
src/config.js   secure config paths and persistence

npm test                  # Node built-in test runner
scripts/build-deb.sh      # -> dist/stoke_<version>_all.deb
scripts/publish-deb.sh dist/stoke_<version>_all.deb heavy-duty stable main

Tag v* to release: CI runs tests, builds the .deb, publishes to the heavy-duty Debian registry, and attaches the package to the release (needs a runner + RELEASE_TOKEN with package/repo write).

1. Bump version in package.json / lockfile
2. Commit, tag v<version>, push the tag
3. Consumers: apt-get update && apt-get upgrade

---

Security

• Tokens on disk: mode 0600. Passwords are never stored.
• Prefer --password-file or STOKE_PASSWORD over -p (shell history / ! expansion).
• Interactive password prompts do not echo.
• stoke api is a full authenticated passthrough — never feed it untrusted strings in the path or body.
• stoke repo clone never writes the token into the remote URL or .git/config.

---

Docs

Doc	Contents
docs/COMMANDS.md	Full command reference
docs/DESIGN.md	Brand system and landing design

---

Why “stoke”?

Heavy-duty tools are one syllable, plain English, industrial, and often a verb⇄noun: cast, rig, jig, boss, hand. The Forgejo instance is the forge. To stoke a fire is to tend it and keep it burning — this CLI does that for issues, PRs, imports, and org setup.

Rejected names included forge (the platform, not the tool), weld / quench (wrong metaphor), and flux (reads as chemistry, not the shop floor).