ci / test (pull_request) Has been cancelled

Details

docs: shorten README and move command reference to docs/COMMANDS.md

Keep the README scannable (install, quick start, capability map, config,
security, develop) and put full options/examples/API mapping in
docs/COMMANDS.md without dropping detail. Ship COMMANDS.md in the npm
package files list.

2026-07-26 23:11:30 +00:00

5 KiB

Raw Permalink Blame History

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).

Bump version in package.json / lockfile
Commit, tag v<version>, push the tag
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).

5 KiB Raw Permalink Blame History Unescape Escape