Skip to main content

​
Prerequisites

  • Node.js 20.12 or later and npm installed
  • An application project for the guided integration
  • Access to your DNS provider for custom subdomain setup

​
Get started

Run this command from your application’s root directory:
The CLI opens your browser to sign in or create an account, detects your stack, provisions API keys, and offers to apply the integration to your code. No global installation is required. The CLI supports common frontend frameworks and Node.js and Python backends. See the supported stacks for details. For other detected stacks, it offers an experimental, docs-based integration.

​
Guided integration

The CLI checks what’s already configured and applies the first missing step. The guided setup covers:
  1. Identify visitors: install and configure the frontend integration to identify devices and generate identification events.
  2. Verify events on your backend: add a Server API call to retrieve identification results and Smart Signals for server-side decisions.
  3. Protect against ad blockers: set up a custom subdomain and update your app to use it once it’s active.
Review and test each change before choosing the next step from the menu. If your backend lives in a separate repository, the CLI asks for its directory when you choose server-side verification. The CLI changes your local project, not your deployment settings. Public keys belong in frontend configuration and secret keys must remain server-side. Review your changes before committing, keep environment files containing secrets out of version control, and add the required variables to your hosting platform before deploying.

​
Custom subdomains

Choose Protect against ad blockers with a custom subdomain in the guided setup, or go directly to that step:
Use an unused subdomain of a domain you own, on the same primary domain as your app. The CLI registers it, or continues an existing one, and then adds the DNS records: when your DNS provider supports Domain Connect, it opens the provider in your browser for you to approve; otherwise it shows the records to add at your DNS provider (see Add DNS records). The CLI waits up to five minutes for the subdomain to become active, then asks before updating your app’s Fingerprint configuration. If DNS takes longer, finish later: run the same command again, or accept the resume offer on the next npx fingerprint integrate, in the same project and workspace.
On Cloudflare, use DNS only rather than Proxied for the routing A records and verification CNAME. Proxying can prevent validation even when you entered the correct values.
To manage subdomains without touching your application code, use the fingerprint subdomains commands. They take --json for scripts and coding agents.

​
Commands

Prefix these commands with npx if you haven’t installed the CLI globally. For the subdomains subcommands and every option, including --json output, --ci for non-interactive runs, and --verbose for a detailed log, see the CLI README or run a command’s --help.

​
Troubleshooting

  • Records aren’t validating: compare the host and value of each pending record with your DNS provider. On Cloudflare, check DNS only. See subdomain statuses.
  • All records are validated, but the subdomain is pending: certificate setup is still running. Check its status later with npx fingerprint subdomains get metrics.example.com; don’t recreate it.
  • Authentication failed: run npx fingerprint login to sign in again.
  • The browser can’t reach the CLI: sign-in and Domain Connect continue through a local callback on the same machine. Remote sessions need port forwarding.
For integration issues, run with --verbose. The detailed log is fingerprint-wizard.log in your system’s temporary directory. Review it before sharing it with Fingerprint support or in a CLI issue.