Reference
Terminal commands
The faundr CLI ships with the plugin. Your AI agent uses it under the hood for the /faundr:… commands, and you can use it directly too. This page lists every command, grouped by topic.
How to run a command
You can run a Faundr command in three ways:
- Inside Claude Code, with
!in front:!faundr board. The command runs right away and its output stays in the conversation, where the agent can see it too. - By asking the agent: "add task X to Faundr". It runs the right command on its own.
- In a regular terminal, in the project folder:
faundr board. For this, the plugin has to be installed andfaundrhas to be on your terminal's path. Inside the agent, it already is.
A few rules apply to every command:
- Text without quotes works.
faundr task Build the login screenis the same asfaundr task "Build the login screen". Use quotes when the text contains symbols your terminal treats specially (|,>,&). - Options take a space. Write
--days 30. The--days=30form doesn't work. - Most commands need you signed in and a linked folder. Without signing in, you'll see "No token. Sign in first". Without a linked folder, you'll see "Folder not linked to a project. Use /faundr:link first". The exceptions are marked works offline.
- The CLI doesn't use your AI plan. It either runs local analysis without AI or assembles context for the agent to read. The thinking is done by the agent, guided by the agent commands. The one exception is
faundr browse, where Jev, an outside service, picks the clicks.
faundr --help (or any name the CLI doesn't recognize) only prints the list of command names, with no explanation of each. Use this page as your reference.Account and connection
| Command | What it does |
|---|---|
faundr setup [--refresh] | Sets up Faundr in the project in one pass, like /faundr:setup. It does the safe parts on its own and, in a regular terminal, asks yes or no for each item that touches project files. It also lists what uses AI, with the estimated cost. --refresh rebuilds the map and reruns the checks. Other options: --apply <items> and --skip <items> (apply or leave out without asking: git, gitignore, statusline, agents-md, codex-rules, supabase-token, errors), --no-ask (report only), and --economy all / --no-economy (turn the end-of-response economy mode on or off). |
faundr login [--url <address>] | Connects your computer to your account through the browser. It shows a code, opens Faundr and waits for you to click Authorize (up to 5 minutes; if it times out, faundr login --wait picks up where it left off). The token is created on your computer and never goes through the chat. --url is only for pointing at a different Faundr server. |
faundr link [<project name or id>] | Links the current folder to a project. It accepts the exact name (case doesn't matter) or the id. On its own, it lists the projects you can link. It writes the .faundr.json file to the folder. |
faundr status | Shows whether everything is connected: the server in use, the start of your token, the linked project, the git branch, whether the code map exists and where the plugin's error log lives. Works offline. |
faundr config lang [en|pt|auto] | Sets the language of what the plugin shows you (setup, status bar, findings in the dashboard). On its own, it shows the current one. auto goes back to your computer's language. The agent always replies in the language you write in. |
faundr statusline-install [--force] | Turns on the Faundr status bar at the bottom of the Claude Code screen (project, feature, progress, next step). It won't replace a bar you already have unless you pass --force. |
faundr agents-md [--file <file>] [--off] [--sync] | Copies the team's rules and decisions into AGENTS.md (or another file, like CLAUDE.md) inside a marked block. This lets agents that don't run the plugin, like Cursor, see the team's memory. It's off by default. --off removes the block. Once it's on, the block updates itself every session. |
Faundr finds the project by walking up from folder to folder until it finds
.faundr.json. The folder where that file lives is the project root as far as Faundr is concerned. If you linked the wrong folder, run faundr link again in the right one.Features and tasks
These record what's being built. Everything shows up in Features and in the status bar.
| Command | What it does |
|---|---|
faundr feature "<title>" [--desc "..."] [--done-when "a; b"] | Creates a feature and makes it the current one for this folder. --done-when sets the done-when criteria, with items separated by ;. |
faundr feature "<milestone>" --after current [--desc "..."] | Records the next milestone of work done in phases. It stays planned and doesn't become the current feature. --after takes current or the name (or part of the name) of the previous milestone. |
faundr task "<description>" [--feature "<name>"] | Adds a task to the checklist of the current feature, or of the one you name. |
faundr start "<excerpt or #>" | Marks a task as in progress. |
faundr done "<excerpt or #>" [--already-committed] | Marks a task as done and stores the current commit. If there are uncommitted changes, the task shows as uncommitted in the dashboard until the next git commit. --already-committed is for older work that's already in git, so your current changes don't count against it. |
faundr focus "<name>" | Switches the current feature and shows its checklist. |
faundr board [--all | --memory | --review] | Shows open concerns and the current feature's checklist. --all shows every feature. --memory shows only confirmed rules and decisions. --review shows everything still open (in progress and upcoming milestones), when each was last touched and which have stalled for more than 14 days. It's what /faundr:tidy-board reads. |
faundr feature-discard "<id or name>" | Discards a feature that won't happen. It leaves the tabs and the agent's context, but you can bring it back. |
faundr feature-restore "<id or name>" | Brings back a discarded feature (same as the Restore button in the dashboard). |
faundr criteria ["<criterion>"] [--feature "<name>"] | With no text, lists the done-when criteria and the status of each item. With text, adds an item. |
faundr criteria --remove <#> | Removes a done-when item from the current feature (for example, one added by mistake). |
faundr criteria-check <#> --met | --not-met [--note "..."] | Marks a done-when item as met or not met, with a note on how it was checked. |
Memory: rules, decisions and concerns
Everything shows up in Memory.
| Command | What it does |
|---|---|
faundr decision "<decision>" [--why "<reason>"] [--file "<files>"] [--replaces "<id or excerpt>"] [--global] | Records a technical decision tied to the current feature. Without --file, it ties itself to the files the session edited (when there are 5 or fewer); --global prevents that. --replaces retires the decision this one replaces. If it looks like an existing decision, the command warns you. |
faundr rule "<rule>" [--why "..."] [--file "<files>"] [--forbid "<pattern>"] | Records a team rule. --forbid says what the code must not contain, for example "console\.log\(". Faundr then warns the agent on every edit that introduces the pattern, and the quality check points out where it already exists. |
faundr memory-edit "<id or excerpt>" [--rule | --decision] [--file "<files>"] [--global] [--obsolete] | Changes a rule or decision. It can become a rule (always applies) or a decision, be tied to files, apply to the whole project again or become obsolete. The ids show up in faundr board --memory. |
faundr concern "<what worries you>" [--why "..."] | Records a concern to review later. It gets a number (P-1, P-2…). |
faundr resolve [P-<n>] | Marks a concern as resolved. With no number, it lists the open ones. |
--file takes a file, a folder or a pattern like src/server/** or *.sql, and you can repeat it.
Overview, Stack and variables
| Command | What it does |
|---|---|
faundr stack-scan [--json] | Reads the project's files without AI and detects where each part runs, languages, tools, external services, variables (names only) and scripts. --json shows the result without sending it. It runs automatically at the start of each session. |
faundr env-check [--hosting] [--no-send] | Checks every environment variable: does the code read it? Is it in the example file? Is it in the .env on your computer? Is it on your hosting? It flags what "breaks in production", what's "missing locally" and what's "not in the example". Names only, never values. --hosting queries Cloudflare, Vercel or Netlify through their CLI, which has to be signed in. |
faundr overview-context / overview-save | Used by /faundr:overview to write the Overview. You don't need to run them. |
faundr diagram-save [file] [--feature "<name>"] [--no-wait] | Used by /faundr:planning to send a feature's "how it will work" diagram. The server checks the format, the canvas opens in your browser and the command waits for you to approve or ask for changes. You don't need to run it. |
faundr diagram-wait [--feature "<name>"] | Keeps waiting for your answer on the diagram canvas (the agent uses it when you take longer than 9 minutes). |
faundr architecture-check | Checks which parts of the architecture (the Architecture section) already exist in the code, using each part's paths, and which folders with code fall outside the plan, then sends the result to the dashboard. It runs automatically at the start of each session, without AI. With --pull, it writes the current architecture to .faundr/painel/architecture.json for the agent to edit and send with faundr diagram-save … --architecture. |
faundr stack-context / stack-save | Used by /faundr:stack to review the Stack. You don't need to run them. |
Code map
The map is built on your computer. Queries work offline and without signing in. They read the local map and, before answering, update only the files that changed.
| Command | What it does |
|---|---|
faundr map [question] | On its own, the same as faundr graph. With a question, the same as faundr graph-query. |
faundr graph | Builds (or rebuilds) the code map and sends it to the dashboard. After the first run, it rebuilds itself when the agent edits files. |
faundr graph-query "<question>" [--limit N] [--budget N] | Asks the map a question. It returns up to 8 relevant code excerpts, with what uses them and what they use. |
faundr graph-path "A" "B" | How two pieces of the project connect. If there's no path in the direction of use, it tries once ignoring direction. It never goes through outside packages (like react or node:fs). |
faundr graph-callers "X" [--out | --both] [--depth 2] | What uses X. --out shows the reverse (what X uses), and --both shows both. --depth 2 shows the knock-on effect. |
faundr graph-skeleton <file> | A file's outline: each function with its signature and without its body. |
faundr graph-grep "<text>" [--in <folder>] [-i] | Searches for text and groups the results by the function they appear in, most used first. -i ignores case. |
Security
Findings are numbered S-n and show up in Security. The check runs on your computer and sends only the findings, with keys masked.
| Command | What it does |
|---|---|
faundr security-scan [--files a,b] [--history] | Full check without AI: keys and passwords in the code, .env in git, database rules, packages with known vulnerabilities, rate limits and headers. --history also looks for keys in the git history, which already happens automatically once a week. |
faundr security-show [S-<n> | <package>] | On its own, lists open issues by severity and, separately, the "Needs check" items. With S-n, shows the issue's details and how to fix it. With a package name, shows all of its issues. |
faundr security-resolve S-<n> [--verified "..."] | Re-runs the check and only closes the finding if the problem is really gone. A finding from the AI review needs --verified saying how it was checked. |
faundr security-ignore S-<n> --reason nao-e-problema|aceito-o-risco [--note "..."] [--days N | --days sempre] | Removes it from the list with a reason. The default is 30 days, after which the finding comes back. |
faundr security-report [--out file.md] | Generates the security report in Markdown, to show a partner or paste into an AI. |
faundr security-import <file> | Imports results from another tool: Snyk (snyk test --json), any SARIF file (Semgrep, CodeQL, Gitleaks, Trivy…) or the Supabase Security Advisor. |
faundr security-supabase [--ref <project>] | Runs the Supabase Security Advisor against your real database. It needs your personal Supabase token in the SUPABASE_ACCESS_TOKEN variable, which stays on your computer. |
Database, launch and privacy
| Command | What it does |
|---|---|
faundr db-test [--sql | --result <file>] | Tests your Supabase database as a visitor and as another signed-in user. Reads use the public key from .env. To test writing, updating and deleting, it needs SUPABASE_ACCESS_TOKEN. Without the token, --sql prints the test SQL for the agent to run through Supabase, and --result brings the response back. The test undoes everything at the end. Every open door becomes an S-n. |
faundr launch-check [--url <site>] [--skip-code] | The part of "Ready to launch?" that only your computer can check: the code builds, tests, security, tested database, payment webhook, live site headers, rate limiting and privacy policy. It ends with CAN LAUNCH: YES/NO. Without --url, it uses the production address from the Stack; --skip-code skips build, tests and security. |
faundr privacy | An inventory, without AI, of the personal data the app collects and the companies that receive it. It also lists what's missing for privacy law (LGPD). It reads only field names, columns and packages, never user data. |
Code quality
Findings are numbered Q-n and show up in Code quality.
| Command | What it does |
|---|---|
faundr quality-scan [--files a,b] | Full check without AI: hidden failures, weak types, overly complex code, too much code, cleanup, skipped tests, broken AI instructions, performance and your house rules. |
faundr quality-show [Q-<n>] | Lists the open ones, or shows one with what it is, why it matters and how to fix it. |
faundr quality-resolve Q-<n> [--verified "..."] | Re-runs the check and only closes the finding if the problem is gone. |
faundr quality-ignore Q-<n> --reason falso-alarme|de-proposito|depois [--note "..."] | Removes it from the list with a reason. depois comes back on its own after 30 days. |
faundr quality-reopen Q-<n> | Reopens an ignored finding. |
faundr quality-rule "<name>" --pattern "<pattern>" --message "<why>" [--files "src/**"] [--severity alta|media|baixa] | Creates a house rule: something your team doesn't want to see in the code. It becomes a file in .faundr-regras/, which goes into git with the rest of the project. |
faundr quality-ladder on|off | Turns on or off the reminder, at the start of each session, that tells the agent not to write too much code. |
To skip a piece of code on purpose, write a comment on the line above it:
// faundr-ignore <rule>: <reason>. faundr-ignore-file <rule> applies to the whole file.Tests
Tests never run on their own. They only run when you or the agent ask. See Tests.
| Command | What it does |
|---|---|
faundr tests-scan | An inventory without running anything: which test runners the project uses (Vitest, Jest, Playwright, node --test, pytest, Karma, flutter test, PHPUnit, Pest, go test, Maven, Gradle, dotnet test, cargo test, CTest, make test), how many test files and tests exist, and whether any test seems to use the production database. It runs automatically at session start. |
faundr tests-run [--changed] [--coverage] [--files a,b] [--runner <name>] | Runs the tests and sends the result. --changed runs only what changed since the last commit. --coverage also measures how much of the code is tested. Other options: --exclude, --timeout <minutes> and --python <path>. |
faundr tests-show [T-<n>] | The latest runs and the failing or flaky tests. With T-n, a defect from mutation testing. |
faundr tests-mutation [--files <file>] [--budget <min>] | Mutation testing: it breaks the code on purpose, only in what the session changed, and shows every break no test noticed (each becomes a T-n). It needs Stryker installed and passing tests. The default is 5 minutes. |
faundr tests-ignore T-<n> --reason equivalente|falso-alarme|depois | Removes a defect from the list with a reason. |
faundr tests-map "<feature>" [--tests "a.test.ts"] [--critical] | Ties a feature to the tests that protect it. --critical marks it as "must not break". |
If the tests seem to use the production database,
tests-run and tests-mutation won't run until they get --confirm-db. The safe route is a .env.test pointing at a test database.Faundr never installs anything on its own. If the coverage tool (
@vitest/coverage-v8) or Stryker is missing, it shows you the command to approve.Design
Findings are numbered D-n and show up in Design.
| Command | What it does |
|---|---|
faundr design-lint | Screen check without AI (about 45 rules): identity, mobile, accessibility, contrast, motion, states, off-palette colors and repeated styles. It runs automatically. |
faundr design-show [D-<n>] | With no number, shows the fix order for open findings in 5 stages, from what breaks usage to polish. With a number, shows the details. |
faundr design-resolve [D-<n>] | Marks it as resolved. With no number, lists the open ones. |
faundr design-archive D-<n> --reason nao-se-aplica|falso-alarme|decisao-de-design --note "..." | Archives an issue that doesn't apply to this project, with the reason. It won't come back. |
faundr design-reopen D-<n> | Reopens an archived or resolved finding. |
faundr design-scope [--mobile sim|desktop|celular] [--product app|site|misto] [--theme escuro|claro|ambos] [--motion nenhum|sobrio|expressivo] [--disable <rule>] [--enable <rule>] [--exception "technique — reason"] | Shows or changes the design scope. --mobile desktop stops checking the mobile version. Turning off a rule archives its open findings. |
faundr design-coverage | Shows the coverage of the last full audit: what was checked and the score for each theme. |
Errors
Errors are numbered E-n and show up in Errors. Errors from the agent's commands arrive on their own and close on their own when the same command passes again.
| Command | What it does |
|---|---|
faundr errors [--all | --resolved | --archived] | Lists open errors (or all of them, the resolved ones or the archived ones). |
faundr error-show E-<n> | Where it broke, how many times, which conversation and request it came from, and an excerpt of the output. For errors from the live app, it also shows how many people were affected, what they did beforehand and the original code (using the source maps on your computer). |
faundr error-resolve E-<n> --verified "how you checked" [--next-deploy] | Closes it by hand. --next-deploy is for live app errors: the old version may still send the error without reopening it, and it only comes back if it shows up in a new version. |
faundr error-recipe E-<n> --cause "why it broke" --fix "what fixed it" | Saves the error's recipe. It shows up in faundr error-show when this error comes back or when the same error appears in another file of the project. |
faundr parallel [open "<a>; <b>" | close <name> | --all] | With nothing, lists the stages that can start in parallel now. open opens a workbench (a copy of the project in .faundr/mesas/) for each stage; close closes it, and only deletes it if the work was already merged. Used by /faundr:parallel. |
faundr error-archive E-<n> [--days N | --count N | --users N] | Archives it for N days, until it happens N more times or until it affects N more people. |
faundr error-reopen E-<n> | Reopens an error. |
faundr errors-dsn | Shows the address (DSN) the live app uses to send errors to Faundr and when the last one arrived. |
faundr errors-uptime <https://site> | --off | Checks whether the site is up every 5 minutes. Two failures in a row become an error with an alert, which closes on its own when the site comes back. |
faundr errors-import-sentry --org <org> --project <project> | Brings in open errors from Sentry, if you already use it. The token (SENTRY_AUTH_TOKEN) stays on your computer. |
Restore points
These commands work offline and without signing in. They only need git in the folder. See Disaster protection.
| Command | What it does |
|---|---|
faundr checkpoint ["reason"] | Saves a restore point of your files right now. Faundr already saves points on its own: before the first change of each session, every 30 minutes of edits and before risky commands. |
faundr checkpoints [--limit N] | Lists restore points (1 is the most recent) and what changed after each one. |
faundr restore <#> [--yes] | Without --yes, it only shows what would change. With --yes, it saves the current state as a new point and then restores the files. That means the restore can be undone too, with faundr restore 1 --yes. |
Team
| Command | What it does |
|---|---|
faundr team | Shows who else is working on the project right now: each person's agent, computer, workbench and the files they touched in the last hour. See Working as a team. |
faundr claim "<task>" [--force] | Makes you responsible for the task (it shows your name in the dashboard). If it already belongs to someone else, it warns you and doesn't take it. --force takes it anyway, once you've talked it through. |
faundr release "<task>" | Frees the task so anyone can pick it up. |
faundr own ["<feature>"] [--force] | Makes you the owner of the feature (the current one if you don't name it). If it already belongs to someone else, it warns you and doesn't switch. --force switches anyway, once you've talked it through. |
faundr disown ["<feature>"] | Leaves the feature without an owner. Whoever works on it first becomes the owner. |
faundr inbox | Fetches dashboard requests for you (or for anyone), messages and team notes. |
faundr inbox --done <code> ["what was done"] | Closes a request. It shows as done in the dashboard, with the note. |
faundr inbox --print <code> | Downloads the screenshot attached to a request made with the Chrome extension (the element the person pointed at) into .faundr/pedidos/. |
faundr msg "<text>" [--to "<name>"] | Sends a message to a teammate (or, without --to, to the whole team). It arrives with the next request of whoever has their agent open. |
Skills and workflows
See Workflows.
| Command | What it does |
|---|---|
faundr skills scan | Reads the skills you use in this project (the repo's in .claude/skills and .agents/skills, your personal ones and the ones from enabled plugins, in Claude Code and Codex) and connects them to Faundr. It reads only the name, the description and whether the skill is manual; the content never leaves your computer. It runs on its own at the start of every session and only sends anything when the list changed. |
faundr skills list | The project's skills, grouped by source, with when to use each, its topics and whether it's a connected skill. |
faundr skills when "<name>" [--when "..."] [--topic "..."] [--kind seguranca|testes|qualidade|erros|nenhum] | Saves when to use the skill, the topics that remind the agent of it, and its type (security, tests, quality, errors or none). Any type other than nenhum makes it a connected skill: what it finds goes to that section of the dashboard. |
faundr workflow list | The project's workflows (W-n), with their status: active, draft or off. |
faundr workflow show <W-n or name> | A workflow's steps. |
faundr workflow draft "<name>" --when "..." --topic "..." --step "..." [--file "<folder or pattern>"] | Saves a workflow as a draft. It only takes effect once the owner approves it in the dashboard. |
faundr workflow run <W-n> --why "<request>" | Starts following a workflow. Your team watches the progress live on the canvas. |
faundr workflow step <W-n> <#> [--wait | --skip | --done] [--note "..."] | Marks the current step. --wait shows it's the owner's turn; --skip says the step doesn't apply. |
faundr workflow done <W-n> [--note "..."] / faundr workflow stop <W-n> | Finishes or stops the workflow. |
Fast browser
| Command | What it does |
|---|---|
faundr browse --url <address> --goal "<goal>" [--value "<text>"] [--secret-env <VARIABLE>] | Runs a task on a website. Jev, an outside service, picks each click by reading the page's list of buttons and fields, with no screenshots. Anything that needs typing goes in --value. Passwords go in an environment variable via --secret-env, and Jev only sees "password provided". It opens a hidden Chrome with its own profile, without your accounts. --show shows the window. --chrome uses your own Chrome, with your logins, through the Faundr extension. --shot <file.png> saves a screenshot of the final screen and --style measures the page's fonts, colors and corners. No linked folder needed. |
faundr browse-key --env <VARIABLE> | Saves your Jev key to ~/.faundr/config.json, read from an environment variable (or standard input) so it never shows up in the command. |
Session, handoff and reports
| Command | What it does |
|---|---|
faundr resume | "Where we left off": the previous session (requests, commits, tasks, handoff note) and everything still open in the project. |
faundr handoff "<note>" | Saves the handoff note: one to three sentences about what's half done and what comes next. It appears in Activity → Where you left off and at the start of the next session. |
faundr handover [--out file.md] | Generates the developer handoff pack: a single document with everything someone needs to take over the project. The default is .faundr/relatorios/PASSAGEM.md. |
faundr weekly | The last 7 days in plain language, the same summary that goes to Slack or Discord. |
faundr usage --debug | Shows the usage numbers Insights would receive from the most recent conversation. Use it to check what gets sent. |
Environment variables
| Variable | What it's for |
|---|---|
FAUNDR_TOKEN | Uses this token instead of the one saved by faundr login. Handy on CI servers: sign in on a computer and use the token from config.json (store it as a CI secret, never in the code). |
FAUNDR_API_URL | Uses this Faundr server instead of the saved one. |
SUPABASE_ACCESS_TOKEN | Your personal Supabase token, for security-supabase and db-test. It never goes to Faundr. |
SENTRY_AUTH_TOKEN | Your Sentry token, for errors-import-sentry. It never goes to Faundr. |
TYPESAFE_API_KEY | Your Jev key, for faundr browse. It takes the place of the one saved with faundr browse-key. |
Files Faundr creates
On your computer, in the ~/.faundr/ folder:
config.json: the token and the server address. Only you can read it.hook.log: the plugin's error log. If something in Faundr doesn't seem to work, the explanation is usually here.browse-profile/: the Chrome profilefaundr browseuses, kept separate from yours.- Temporary session markers, deleted after 2 days.
In the project:
.faundr.json: links the folder to the project. Safe to commit..faundr/: everything Faundr stores on this computer, organized by type. It stays out of git because your team sees it through the dashboard. The folder'sLEIA-ME.mdexplains each part:painel/: local copies of the Overview, the Stack, the Showcase, the memory and the file-scoped rules.relatorios/: the handoff pack (PASSAGEM.md) and the security report.mapa/: the code map and the architecture summary.verificacoes/: results of the database test, the hosting variables check and the project's tests.cache/: shortcuts for rebuilding the map faster. Safe to delete.pedidos/: screenshots from requests made with the Chrome extension.state.json: the session state.DESIGN.md: the design guide, at the project root. It goes into git..faundr-regras/: the Quality house rules. Meant to go into git..faundrignore: you create it if you want. It lists folders or files, one per line in.gitignoreformat, that Faundr leaves out of the code map, the architecture's Off-plan list, the design check and the search for project parts (like an app inside another folder, with its own packages and scripts). Use it for third-party code, repos you cloned for reference and generated files.
In git: restore points live in their own area (refs/faundr/checkpoints). They don't touch your branch, your stash or git status. Faundr keeps the 50 most recent.
Internal commands
These commands exist, but the plugin calls them itself. They're listed here so you recognize them if they show up in a log.
| Command | Who calls it |
|---|---|
faundr hook, faundr gate, faundr guard, faundr subagent-start | The plugin's hooks inside your agent. See What Faundr does on its own. |
faundr statusline, faundr status-refresh | The status bar. |
faundr checkpoints-sync, faundr usage-sync, faundr background | Background tasks. |
faundr *-context, *-finding, *-review-done, *-save, design-measure-*, showcase-* | The agent commands (/faundr:…), to assemble context and record what the agent found. |
faundr skill-report "<skill>" --areas <areas> (--file <findings.json> | --none) | The agent, at the end of a response where a connected skill ran. It sends what the skill found and fixed, which becomes S-n, Q-n, T-n or E-n tagged "via /name". Keys are masked. |