rasterstate/fj
rasterstate/fj
2
0
Fork 0
Code Issues Pull requests Actions 2 Packages Projects Releases 1 Wiki Activity
fj/docs/faq.md
Stephen Way faaf522b05
Some checks are pending
ci / check (push) Waiting to run
Details
bugs + agent-focused Forgejo gaps + CI + docs 
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>
2026-05-13 14:52:28 -07:00

3.7 KiB
Raw Blame History

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?

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

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 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?

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?

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.