--- title: CLI reference description: Local pre-PR review with @getfoyer/cli. --- `@getfoyer/cli` runs the same verification locally that the Foyer GitHub App runs on PRs. Catch failures before you push. ## Install ```bash 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 ```bash 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. {/* BEGIN: foyer-cli-commands (managed by scripts/sync-cli.ts) */} | 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 | {/* END: foyer-cli-commands */} ## Flags {/* BEGIN: foyer-cli-flags (managed by scripts/sync-cli.ts) */} | Flag | Applies to | Effect | |---|---|---| | `--version` | global | Print version number | | `--help` | global | Show this help message | {/* AGENT-ONLY: full flag reference. Stripped by the MDX renderer; served verbatim by the /agents/cli raw-markdown route. */} {/* | Flag | Applies to | Effect | |---|---|---| | `--token <tok>` | global | Override saved token for this command | | `--auto-plan-attach` | `setup` | install the pre-push hook without prompting | | `--no-auto-plan-attach` | `setup` | skip the pre-push hook; install editor skills only | | `--since <ref>` | `review` | compare HEAD against <ref> (default: main) | | `--audience <a>` | `review` | 'technical' (default) or 'non_technical' | | `--intent <text>` | `review` | run scope_alignment against this intent text | | `--intent-file <path>` | `review` | read intent text from a file | | `--linear <KEY>` | `review` | fetch intent from a Linear issue (e.g. ENG-123) | | `--no-code-review` | `review` | skip the code_review signal | | `--no-security` | `review` | skip the security signal | | `--run-tests <cmd>` | `review` | run a local test command (e.g. 'yarn test') and include the result as a tests_build signal | | `--json` | `review` | print the RunArtifact v0.1 to stdout (JSON) | | `--report-html <path>` | `review` | write a standalone HTML report to <path> | | `--report-json <path>` | `review` | write the RunArtifact JSON to <path> | | `--upload-report` | `review` | upload artifact to Foyer, print share URL | */} {/* END: foyer-cli-flags */} The default `foyer review` runs every available static signal against `HEAD` vs. `main`. ## What `foyer review` prints A passing run: ```text $ 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: ```text $ 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: ```yaml # .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: ```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: ```bash jq -r .token ~/.foyer/credentials ``` See the [MCP install page](/agents/mcp) for the full pattern. ## See also - [Concepts](/agents/concepts) — what each signal name actually means. - [Signals](/agents/signals) — per-signal reference. - [MCP server](/agents/mcp) — expose the same review surface as MCP tools. - [Troubleshooting](/agents/troubleshooting) — common CLI errors and fixes. --- [agent navigation] - prev: https://docs.getfoyer.dev/agents/setup - next: https://docs.getfoyer.dev/agents/mcp - index: https://docs.getfoyer.dev/llms.txt - human: https://docs.getfoyer.dev/cli