CLI reference

@getfoyer/cli runs the same verification locally that the Foyer GitHub App runs on PRs. Catch failures before you push.

Install

npm i -g @getfoyer/cli
foyer login

foyer login opens a browser and authenticates via RFC 8628 device-code flow. No token copy-paste.

Verify

foyer status

Prints your principal (user or integration token) and current org. For integration tokens it also prints scopes and expiry. Exits 0 on a valid token, 2 if the token is missing or rejected.

Commands

The list below mirrors foyer --help for the latest published CLI.

Command	What it does
`foyer login`	Authenticate via browser (RFC 8628 device-code flow, recommended)
`foyer status`	Print the current principal, org, and token expiry (verifies the token)
`foyer review`	Review your local diff with Foyer's hosted reviewer model
`foyer watch`	Start an explicit local session; type 'checkpoint' to send the diff to hosted Foyer (FOY-11)
`foyer init`	Save a Foyer integration token (legacy paste flow; use --token in CI)
`foyer setup`	Install editor skills (Claude/Codex/Cursor); prompts before installing the pre-push hook
`foyer linear spec <key>`	Fetch a Linear issue spec (e.g. ENG-123)
`foyer plan attach`	Upload the current branch's plan artifact
`foyer plan save`	Save the approved plan-mode plan for upload on push
`foyer plan status`	Show resolved plan status for current HEAD
`foyer plan review`	Pre-implementation review of a plan against repo context
`foyer logout`	Clear saved credentials

Flags

Flag	Applies to	Effect
`--version`	global	Print version number
`--help`	global	Show this help message

The default foyer review runs every available static signal against HEAD vs. main.

What `foyer review` prints

A passing run:

$ foyer review --linear ENG-456
foyer · running verification against HEAD vs main
intent           ENG-456 "add /login redirect on 401"  (high confidence)

  scope_alignment   passed   3/3 requirements met (verdict: exact)
  code_review       passed   no P1 findings
  security          passed   no secrets / dangerous patterns
  hallucinated_api  passed   all references resolve
  template_cruft    passed
  dependency_hygiene passed
  dead_code         passed

✅  ready to push

A failing run with a repair prompt:

$ foyer review
foyer · running verification against HEAD vs main
intent           PR body  (medium confidence)

  scope_alignment   passed   2/2 requirements met (verdict: exact)
  code_review       FAILED   1 P1 finding
  security          passed
  hallucinated_api  passed
  template_cruft    passed
  dependency_hygiene passed
  dead_code         passed

❌  1 signal failed (code_review). Repair prompt:

  > api/src/auth.ts:47 returns undefined when the session cookie
  > expires. Users hit a white screen. Fix: add a null check and
  > redirect to /login. Two lines.

Run with --report-html to write a standalone HTML report, or
--upload-report to push the artifact and print a share URL.

The structured JSON form (--json / --report-json) is the machine-readable artifact consumed by Foyer's MCP server and the CI example below.

CI example

A typical pre-merge CI check that fails the job on any failed signal:

# .github/workflows/foyer-review.yml
name: foyer
on: pull_request
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm i -g @getfoyer/cli
      - run: foyer review --token "$FOYER_TOKEN" --report-json review.json
        env:
          FOYER_TOKEN: ${{ secrets.FOYER_TOKEN }}
      - uses: actions/upload-artifact@v4
        with:
          name: foyer-review
          path: review.json

For long-lived CI tokens, mint one at app.getfoyer.dev/orgs → Settings → Integration Tokens and store it as FOYER_TOKEN in the repo's Actions secrets. The GitHub App is the recommended path for most teams — the CLI in CI is for setups where the App can't run.

Where the credentials live

After foyer login, the token is stored at ~/.foyer/credentials as JSON:

{ "token": "...", "expires_at": "..." }

If you need the raw token (for example, to wire it into an MCP server), read it with jq so trailing newlines don't sneak in:

jq -r .token ~/.foyer/credentials

See the MCP install page for the full pattern.