forked from heavy-duty/stoke
grok-reviewer-andresmgsl
2dcd8e6f1b
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.
139 lines
5 KiB
Markdown
139 lines
5 KiB
Markdown
# stoke
|
||
|
||
> CLI for the heavy-duty forge ([Forgejo](https://forgejo.org/)). 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`](https://forgejo.heavyduty.builders).
|
||
|
||
Built with [Commander.js](https://github.com/tj/commander.js/). Node.js **≥ 22.12** required.
|
||
|
||
---
|
||
|
||
## Install
|
||
|
||
**Debian / Ubuntu (recommended)**
|
||
|
||
```bash
|
||
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**
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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](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](docs/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](docs/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
|
||
|
||
```text
|
||
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
|
||
```
|
||
|
||
```bash
|
||
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](docs/COMMANDS.md) | Full command reference |
|
||
| [docs/DESIGN.md](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).
|