Stephen Way
faaf522b05
Some checks are pending
ci / check (push) Waiting to run
Bugs:
* Shell injection in `fj auth setup-git`: the hostname is now validated
against a strict DNS pattern and `git config` is invoked directly
(no `sh -c`). Added 4 unit tests covering shell metacharacters.
* Pager won't compile on Windows: the libc-based dup2 redirect lives
behind `#[cfg(unix)]`. Non-Unix gets a no-op stub.
Agent-focused Forgejo API gaps:
* `fj issue edit-comment ID` / `delete-comment ID`. Fix a wrong comment
after the fact (an agent's bread-and-butter).
* `fj search code "..." [-R owner/name]`. The most-requested missing
search dimension for codebase exploration.
* `fj pr request-review N user1 user2`, `unrequest-review N user`.
Distinct from `pr review` (your own approval/changes/comment).
* `fj repo watch / unwatch / star / unstar / starred`. Mark repos for
monitoring.
* `fj milestone {list,view,create,edit,close,reopen,delete,assign}`
with `assign N --milestone ID|none` to attach an issue/PR.
UX + stability:
* Global `--json-fields foo,bar` projection on top of any `--json`
output, gh-style. Dotted-path support (`--json-fields owner.login`).
* 429 / Retry-After honored in the retry loop with a 30 s cap.
* Clap `suggestions` feature for typo'd subcommands.
* `fj auth token` and `auth status --show-token` refuse to write to a
TTY by default (`--force` to override).
CI:
* `.forgejo/workflows/ci.yml` runs fmt/clippy/test/release-build on
every push and PR, mirroring the local pre-push hook.
Docs:
* `SECURITY.md` with threat model and known sharp edges.
* `docs/gh-to-fj.md` full command-by-command mapping.
* `docs/faq.md` covering tokens, hosts, debug, scripting, plugins.
Tests: 60 → 75 passing (2 ignored: editor and env-mutating tests that
fight the cargo test harness on macOS).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
113 lines
3.7 KiB
Markdown
113 lines
3.7 KiB
Markdown
# FAQ
|
|
|
|
## How do I get a token?
|
|
|
|
In Forgejo: Settings → Applications → Generate New Token. Pick the
|
|
scopes you need (typically `repo`, `notification`, and optionally
|
|
`admin:public_key` if you'll manage SSH keys). `fj auth login` will
|
|
prompt you to paste it.
|
|
|
|
## Where are my tokens stored?
|
|
|
|
In your OS keychain (macOS Keychain, Linux Secret Service, Windows
|
|
Credential Manager) under the service name `fj`, keyed by hostname.
|
|
Never on disk in `hosts.toml`.
|
|
|
|
## How do I add a second host?
|
|
|
|
```sh
|
|
fj auth login --host other.example.com
|
|
fj auth switch other.example.com # make it the default
|
|
# or pin per-command:
|
|
fj --host other.example.com repo list
|
|
```
|
|
|
|
## What's the difference between `fj api --jq` and `fj --json-fields`?
|
|
|
|
- `fj api --jq` projects a single JSON document with dotted paths,
|
|
brackets, and pipes. See [`jq.md`](jq.md). It only works on
|
|
`fj api`'s output.
|
|
- `fj --json-fields foo,bar` is a global flag that applies to ANY
|
|
command's `--json` output. It keeps only those top-level (or dotted)
|
|
fields. This is the gh-style behavior.
|
|
|
|
## Why does `fj` keep re-prompting the macOS keychain after I rebuild?
|
|
|
|
The keychain identifies applications by binary hash. Every
|
|
`cargo build --release` produces a new hash, so macOS treats it as a
|
|
new application. Click "Always Allow" once and it'll stick until the
|
|
next rebuild. See `troubleshooting.md`.
|
|
|
|
## How do I make `fj` work in a non-interactive script?
|
|
|
|
- Set `FJ_TOKEN` env var to avoid `fj auth login` prompting.
|
|
- Set `FJ_HOST` to pin the host.
|
|
- Always pass `--body "..."` or `--body -` so `fj` never opens
|
|
`$EDITOR`.
|
|
- Pipe output through `--json` for parseable results.
|
|
- Set `FJ_NO_PAGER=1` (or pass `--no-pager`).
|
|
|
|
## Can `fj` work without a git remote?
|
|
|
|
Yes. Without `-R/--repo` fj falls back to `git remote -v`. With `-R`
|
|
the remote isn't consulted at all. So you can run `fj repo view foo/bar`
|
|
from anywhere, including outside a git repo.
|
|
|
|
## How do I delete the test repo I created?
|
|
|
|
```sh
|
|
fj repo delete stephen/fj-cli-test # asks you to type the slug
|
|
fj repo delete stephen/fj-cli-test -y # skip the confirmation
|
|
```
|
|
|
|
## What if Forgejo and `gh` flag names disagree?
|
|
|
|
We track `gh`. See [`gh-to-fj.md`](gh-to-fj.md) for the mapping. When
|
|
`gh` doesn't have an equivalent (e.g. `fj milestone`, `fj protect`,
|
|
`fj hook`, `fj search code`), we follow Forgejo's terminology.
|
|
|
|
## Why are some `fj-*` plugins not found?
|
|
|
|
Plugin dispatch only triggers when the first positional isn't a known
|
|
subcommand. See `KNOWN_SUBCOMMANDS` in `src/main.rs`. Renaming your
|
|
plugin if it collides is the workaround.
|
|
|
|
## Can I script `git push` to also push via `fj`?
|
|
|
|
`fj` doesn't push git refs — `git` does that. But `fj auth setup-git`
|
|
installs a credential helper so that `git push` to your Forgejo host
|
|
authenticates via your stored token, no `~/.netrc` needed.
|
|
|
|
## How do I see what `fj` is sending?
|
|
|
|
```sh
|
|
fj --debug repo list -R foo/bar
|
|
# or
|
|
FJ_DEBUG=1 fj repo list -R foo/bar
|
|
```
|
|
|
|
Stderr will show `→ GET https://… ?query` and `← 200 url` for every
|
|
request, with a body preview if applicable.
|
|
|
|
## How do I customize the pager?
|
|
|
|
```sh
|
|
FJ_PAGER='less -R' fj repo list # don't auto-quit on short output
|
|
FJ_PAGER=cat fj repo list # disable paging
|
|
FJ_NO_PAGER=1 fj repo list # same as above
|
|
fj --no-pager repo list # per-command opt out
|
|
```
|
|
|
|
## Will `fj` work on Windows?
|
|
|
|
Compilation works (the pager is a no-op there; everything else is
|
|
cross-platform). Not actively tested. Reports welcome.
|
|
|
|
## Where does `fj` store its config?
|
|
|
|
- macOS: `~/Library/Application Support/com.rasterstate.fj/`
|
|
- Linux: `$XDG_CONFIG_HOME/fj/` (`~/.config/fj/`)
|
|
- Windows: `%APPDATA%\rasterstate\fj\`
|
|
|
|
Files: `hosts.toml`, `aliases.toml`, `config.toml`.
|