#fj CLI

fj is a native command-line tool for Forgejo and Gitea-compatible forges: open PRs, triage issues, ship releases, tail Actions logs, and drive workflows from one signed binary. It tracks the Forgejo /api/v1 surface, is multi-host from day one, and keeps tokens in your OS keychain rather than on disk.

This page is the entry point; every command group has its own reference page in the sidebar, generated from fj --help so it always matches the installed binary.

#Install

brew tap rasterandstate/tap
brew install fj

#Authenticate

Log in once. The token is stored in the macOS Keychain, the Linux Secret Service, or the Windows Credential Manager, never on disk.

fj auth login                 # paste a token for the current host
fj auth login --host git.example.com
fj auth status                # show the active host and account

See fj auth for the full set, including setup-git, token, switch, and refresh.

#Repository context

Almost every command is repo-scoped. Inside a clone, fj infers the repository and host from the git remote (preferring upstream, then origin), so you rarely pass -R. Outside a clone, name the repo explicitly:

fj pr list                    # uses the current clone's remote
fj pr list -R owner/name      # explicit repository

#Global flags

These work on every command:

• --host <HOST> (or FJ_HOST) — target a specific host instead of the current default or the one inferred from the remote.
• --debug (or FJ_DEBUG=1) — log every HTTP request to stderr.
• --no-pager — do not pipe long output through $FJ_PAGER / $PAGER.
• --json-fields <FIELDS> — keep only these fields in any --json output; dotted paths like user.login are supported.
• -h, --help / -V, --version.

#Common tasks

# Pull requests
fj pr create --title "Add widget" --body "..."
fj pr checkout 42
fj pr review 42 --event approve --body "LGTM"
fj pr merge 42 --squash --delete-branch

# Issues
fj issue create --title "Bug: ..." --body "..."
fj issue list --state open --label bug

# Releases
fj release create v1.2.3 --title "1.2.3" --asset dist/app-x86_64.tar.gz

# Actions
fj run list -L 10
fj run view 42 --log-failed
fj workflow run deploy.yml --ref main

# Scripting and agents: JSON projection + a raw, paginated API with a jq-ish path
fj pr list --json --json-fields number,title,user.login
fj api /repos/owner/name/issues --paginate -q '.[].title'

#Command reference

Every group below has a dedicated page with usage, arguments, and flags for each of its subcommands.

Core  repo · issue · pr · release · search · browse · status

Actions  run · workflow · secret · variable

Project metadata  label · milestone · protect · hook

Account and host  auth · instances · org · ssh-key · gpg-key

Power and config  api · alias · config · extension · completion · man

Preview  work · stack · agent

#On a runner

Install fj inside a workflow with setup-fj-action (checksum-pinned, from your Forgejo releases), then script your forge from CI. fj-fanout-dispatch-action uses it to fan a workflow_dispatch out across many repos.

#For agents

fj ships a Claude Code plugin so AI agents can drive it from natural-language requests, plus the --json / --json-fields projection for scripts. The agent group adds AI-assisted review, fix, and explain. (These docs were built and shipped with fj.)