Skip to content
Launch price$9/moLock it in

CLI reference

Package @nitpickhq/cli, command nitpick. Run it without installing: npx -y @nitpickhq/cli@latest <command>.

Configuration lives in ~/.config/nitpick/config.json (permissions 0600). Override with environment variables:

Variable Meaning
NITPICK_TOKEN Agent token (npt_...), used instead of the saved login
NITPICK_API_URL Address of the Nitpick API

Commands

Command What it does
nitpick login Log in through the browser. Prints a code, opens the page and waits. In the browser you create an account or log in, start the subscription if you have none, and press Allow. Then it saves the token.
nitpick logout Revoke the saved token on the server and remove it from your machine. If the server cannot be reached, the saved token is still removed and the message says it may still be valid there. Never revokes NITPICK_TOKEN.
nitpick whoami Show the account, the state of the subscription (active, grace, locked or inactive, with the end of the paid period and the renew address) and, from 80% of the limit, the reports used this month. --json for JSON.
nitpick init Add Nitpick to the app in this folder or below it: link or create the app, write nitpick.json, add the package, set up the configuration where it is clear and print the remaining steps. Flags below.
nitpick doctor Check the setup of the app in this folder. Changes nothing. Flags below.
nitpick apps list List your apps with their open counts, and how many are locked.
nitpick apps create --name <name> --platform <swiftui|react-native> Create an app and print its public key.
nitpick feedback list List feedback. Filters below, plus --json.
nitpick feedback show <id> Show one report. --json, and --screenshot <path> to save the image.
nitpick feedback resolve <id> Mark a report resolved.
nitpick feedback reopen <id> Mark a report open again.
nitpick stats --app <id> Open counts by screen, element and app version.
nitpick settings show --app <id> Show which kinds of feedback are on and the texts per language. --json for JSON.
nitpick settings set --app <id> ... Change the settings. Flags below.
nitpick tokens list List the tokens of your account: name, start of the token, last use. The one in use is marked. --json for JSON.
nitpick tokens revoke <id> Revoke a token at once. --json for JSON.
nitpick mcp Start the MCP server on stdio.

init and doctor

Run them in the folder of the repository, or above it: they also find the app in a subfolder (not in node_modules, Pods, build, DerivedData, .git or hidden folders). init needs a valid login; doctor does not (without one it skips the check that the app is on your account).

nitpick init does the installation, in this order: it picks a mode, checks the login, finds the app, checks what it is about to change (iOS 17 or newer, a generated project, the project format, uncommitted git changes), links or creates the app and writes nitpick.json (public key, safe to commit), adds the package, writes the configuration line where it is sure of the code, and prints the steps that remain. It never changes build settings and never replaces an app that nitpick.json already links. If your account already has apps and you give neither --app, --name nor a nitpick.json, init does not create another app: in agent mode it stops with exit 4 and the list of your apps (name, id, platform; with --json the status is needs_app_choice), and a person is asked which one. Choose with --app <id>, or create a new app on purpose with --name "<new name>". Xcode can stay open; init then warns that it can keep an older copy of the project in memory.

Flag Meaning
--app <id> Link exactly this app (the Setup page in the dashboard puts the id in its prompt). If the app is not on the account you are signed in with, init stops with exit 4, names that account and writes and creates nothing.
--name <name> App name to link or create (default: from the project). A name that exactly matches one of your apps links that app; any other name creates a new app on purpose.
--platform swiftui|react-native Default: detected.
--mode human|agent human asks questions, agent never does and never reads stdin. Default: NITPICK_MODE, else human in a terminal and agent elsewhere.
--project <path> The app to change: its folder, or its .xcodeproj. Needed when there is more than one.
--target <name> The app target to add Nitpick to. Needed when a project has more than one.
--yes Do not ask for confirmation of the overview (human mode).
--dry-run Only show what init would change.
--replace Link or create another app although nitpick.json already links this folder to one: --replace --app <id> links another of your apps, --replace --name "<new name>" creates a new one. If the file links an app that is not on the account you are signed in with, init stops with exit 4 and names that account; sign in with the right account (nitpick login) or use --replace --app <id>.
--register-mcp claude|codex|all Also register the MCP server with Claude Code, Codex or both. A failed registration is a warning.
--json JSON output: {status, app, changes, warnings, notes, next_steps}.

The status is ok (init changed something, for example wrote nitpick.json), already_set_up (the package and the configuration are really there; a second run changes nothing) or steps_open (a repeated run that changed nothing while something is still left that init does not do). The first run on a generated XcodeGen or Tuist project, an older project format, code init did not recognise, or a package pinned below 0.3.0 is ok, because init wrote nitpick.json: the manual step is under Notes in the output. With --dry-run it is dry_run.

nitpick doctor checks nitpick.json (valid, and the app is on your account), the package, the link with the app target, the iOS minimum, the configuration call and, for Xcode projects, that the package resolves. Each check is ok or FAIL with the fix. The resolve runs xcodebuild -resolvePackageDependencies in temporary folders and downloads the package.

Flag Meaning
--project <path> The app to check: its folder, or its .xcodeproj.
--target <name> The app target to check. Needed when a project has more than one.
--skip-resolve Do not run the resolve (it downloads the package).
--json JSON output: {ok, project, checks: [{id, ok, message, fix?}]}.

Exit codes of the CLI: 0 success, 1 an error (for doctor: a check failed), 2 an invalid NITPICK_MODE (other usage errors, such as an unknown flag or a value outside the list, give 1), 3 no valid login (init only: run nitpick login), 4 the user has to choose or do something first (pick a project, target or app, raise the iOS target, confirm). See Troubleshooting.

Filters for feedback list

--app, --status open|resolved|all (default open), --kind general|specific, --screen, --element, --app-version, --platform ios|android, --since <ISO time>, --limit 1..100 (default 25).

Flags for settings set

--app <id> is required. Then at least one of:

  • --general on|off and --specific on|off: the two kinds of feedback. With both off, the tab disappears.
  • --footer <language>=<text>: the sentence under Send, for one language. Repeat the flag for more languages. An empty text (--footer nl=) removes it, so the component's own translation shows.
  • --thanks <language>=<text>: the thank-you after sending, the same way.
  • --json: prints {settings, changes: [{field, from, to}], note}.

Language codes are case sensitive: en, nl, de, fr, es, pt, it, pl, tr, ru, uk, sv, da, nb, ja, ko, zh-Hans, zh-Hant, ar, hi. Without a flag that changes something you get an error with the help text. The output shows the old and new value of each changed field, and this sentence: "Changes reach your users within a minute, the next time the app starts or comes back after more than an hour in the background." More in Settings.

Logging in

nitpick login asks the platform for a session, shows a code like ABCD-1234 and opens your browser. It says: "Opening your browser. Sign in or create an account there; if you have no subscription yet, you can start it on the same page." You log in or create an account, start the subscription if needed ($9 per month, excluding VAT where it applies), check the code and press Allow. The CLI polls every 2 seconds and the code is valid for 30 minutes. The token is returned exactly once, and only when the subscription runs. See Billing and limits.

The subscription in the output

  • In the states grace, locked and inactive every command writes one line to stderr, never to stdout, so --json output stays clean. For example: "Nitpick: the subscription has ended; new reports are locked (3 reports locked now). Renew:
    ".
  • From 80% of the monthly limit a second line says how many of the 2,000 reports are used, and at the limit that the tab is hidden until the first of the next month.
  • apps list, feedback list and stats add how many reports are locked, when that is more than 0. Locked reports are never shown.
  • At 402 you get "This report is locked until the subscription is renewed:
    " for a report, or "This needs an active subscription:
    " for creating an app or a token. Only renewing helps, so there is no advice to try again.
  • At 409 limit_reached (50 apps or 25 tokens) the message names what to clean up, with nitpick apps list or nitpick tokens list and nitpick tokens revoke <id>.

Example

nitpick feedback list --status open --screen Home --json
nitpick feedback show 7f3a9c1e --screenshot ./shot.png
nitpick feedback resolve 7f3a9c1e
nitpick settings set --app 3b1d --specific off --thanks nl="Bedankt, we kijken ernaar"
nitpick tokens list