> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fingerprint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fingerprint CLI

> Integrate Fingerprint into your app and manage API keys and custom subdomains from your terminal.

## Prerequisites

* [Node.js](https://nodejs.org/) 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:

```bash theme={"theme":"github-dark-dimmed"}
npx fingerprint
```

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](https://github.com/fingerprintjs/fingerprint-cli#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](#custom-subdomains) 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:

```bash theme={"theme":"github-dark-dimmed"}
npx fingerprint integrate --subdomain metrics.example.com
```

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](/docs/custom-subdomain-setup#2-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.

<Warning>
  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.
</Warning>

To manage subdomains without touching your application code, use the `fingerprint subdomains` [commands](#commands). They take `--json` for scripts and coding agents.

## Commands

Prefix these commands with `npx` if you haven't installed the CLI globally.

| Command | Purpose |
| - | - |
| `fingerprint` | Start the guided setup |
| `fingerprint integrate` | Integrate the current project |
| `fingerprint integrate --subdomain <hostname>` | Start or resume the custom subdomain step |
| `fingerprint keys [public\|secret]` | Print an API key for the signed-in workspace |
| `fingerprint login` / `fingerprint signup` | Sign in or create an account through the browser |
| `fingerprint whoami` | Show the signed-in workspace |
| `fingerprint logout` | Delete the local credential |
| `fingerprint subdomains` | Manage custom subdomains without editing your app |

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](https://github.com/fingerprintjs/fingerprint-cli#commands) 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](/docs/custom-subdomain-setup#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](https://fingerprint.com/support/) or in a [CLI issue](https://github.com/fingerprintjs/fingerprint-cli/issues).