The FusionAuth CLI is a command line tool for interacting with FusionAuth. It is written in Typescript and is available as an NPM package.
- A supported LTS version of Node.js — 22.22.0 or newer (tested in CI on 22, 24 and 26)
- A FusionAuth instance (download it here: https://fusionauth.io/download)
To install and use @fusionauth/cli, run the following commands:
npm i @fusionauth/cli;
npx fusionauth --help;You can install it globally for ease of use from anywhere, but global installations can potentially lead to conflicts and are not recommended:
npm i -g @fusionauth/cli;
fusionauth --help;Currently, the CLI supports the following commands:
- Application management
fusionauth application:create --name <name> --profile <spa|native|webapp> --redirect-uri <uri...> [--authorized-origin-url <url...>]- Create an application in one of a few pre-defined, standard security profiles (spa, native, or webapp), automatically configuring the associated OAuth/JWT settings (and CORS headers, for spa — native apps don't go through a browser's CORS enforcement, so this is skipped for native).--authorized-origin-urlis required if the app will make cross-origin requests from the browser, since enabling CORS alone doesn't allow any origin through — the origin still needs to be added to the system's CORS allowlist.fusionauth application:create [--name <name>] --data <json|@file.json>- Create an application from a full custom JSON configuration, for cases the standard profiles don't cover. The JSON's ownnamefield is used unless--nameis explicitly passed, in which case it overrides the JSON.fusionauth application:update <application-id>- Updates an application with provided data--host- Required. Provide a FusionAuth host URL or add it via an environment variable (FUSIONAUTH_HOST)--key- Required. Provide an API key with permissions for updating the given application or add via an environment variable(FUSIONAUTH_API_KEY)-d, --data <path-to-json-file>- Provide a data file containing all the properties you wish to update constructed like the body of an application update-p, --prop <property.to.change=value>- Update a single property in the application
fusionauth application:get <application-id>- Get a JSON representation of an application's settings--host- Required. Provide a FusionAuth host URL or add it via an environment variable (FUSIONAUTH_HOST)--key- Required. Provide an API key with permissions for updating the given application or add via an environment variable(FUSIONAUTH_API_KEY)-o, --output- Optional. Writes the JSON object to the indicated file
- Common config check
fusionauth check:common-config- Checks to make sure common configuration settings are set.
- OAuth 2.1 compliance check
fusionauth check:oauth-2-1- Checks FusionAuth configuration for OAuth 2.1 compliance.
- Applications (beta)
fusionauth application:create --name <name> --profile <spa|native|webapp> --redirect-uri <uri...> [--authorized-origin-url <url...>]- Create an application in one of a few pre-defined, standard security profiles (spa, native, or webapp), automatically configuring the associated OAuth/JWT settings (and CORS headers, for spa — native apps don't go through a browser's CORS enforcement, so this is skipped for native).--authorized-origin-urlis required if the app will make cross-origin requests from the browser, since enabling CORS alone doesn't allow any origin through — the origin still needs to be added to the system's CORS allowlist.fusionauth application:create [--name <name>] --data <json|@file.json>- Create an application from a full custom JSON configuration, for cases the standard profiles don't cover. The JSON's ownnamefield is used unless--nameis explicitly passed, in which case it overrides the JSON.
- Emails
fusionauth email:download- Download a specific template or all email templates from a FusionAuth server.fusionauth email:duplicate- Duplicate an email template locally.fusionauth email:html-to-text- Convert HTML email templates to text, where the text template is missing.fusionauth email:upload- Upload a specific template or all email templates to a FusionAuth server.fusionauth email:watch- Watch the email template directory and upload changes to a FusionAuth server.fusionauth email:create- Create a new email template locally. Fake user generationfusionauth import:generate- Generate JSON for importing fake users for testing.
- Kickstart (beta test)
fusionauth kickstart:install [dir]- Generate the appropriate files to kickstart and install FusionAuthfusionauth kickstart:start- Run in the directory of a FusionAuth Docker image to run the imagefusionauth kickstart:stop- Run in the directory of a FusionAuth Docker image to stop the imagefusionauth kickstart:kill- Run in the directory of a FusionAuth Docker image to shutdown and wipe the FusionAuth instance
- Apply Configuration
fusionauth apply --file <path>- Apply a kickstart configuration file to a FusionAuth instance. Supports additional variable substitution with the following patterns:#{DEFAULT_TENANT_ID()}- Fetch the default tenant ID from the FusionAuth instance#{ENV.VARIABLE_NAME}- Access environment variables#{PROMPT('message')}- Prompt user for input (displays value in console)#{PROMPT_HIDDEN('message')}- Prompt user for input (hides value, suitable for passwords)
- Lambdas
fusionauth lambda:update- Update a lambda on a FusionAuth server.fusionauth lambda:delete- Delete a lambda from a FusionAuth server.fusionauth lambda:retrieve- Download a lambda from a FusionAuth server.
- Messages
fusionauth message:download- Download a specific message template or all message templates from a FusionAuth server.fusionauth message:upload- Upload a specific message template or all message templates to a FusionAuth server.
- Themes
fusionauth theme:download- Download a theme from a FusionAuth server.fusionauth theme:upload- Upload a theme to a FusionAuth server.fusionauth theme:watch- Watch a theme directory and upload changes to a FusionAuth server.
- Telemetry
fusionauth telemetry:enable- Enables telemetry collectionfusionauth telemetry:disable- Disables telemetry collection
Instead of supplying the API key with the -k option on every command, you can set the FUSIONAUTH_API_KEY environment variable.
The same goes for the host URL option -h, which can be set with the FUSIONAUTH_HOST environment variable.
The download and retrieve commands will succeed even if there are no templates or lambdas to retrieve.
By default, the FusionAuth CLI collects data about your usage. We use this to judge effectiveness of the CLI, check performance and reliability, and help drive new features and improvements. An anonymized unique ID is generated, and function usage information is stored by PostHog.
The CLI never transmits your payloads or command parameters.
If you'd prefer not to send usage data, run the following command:
npx fusionauth telemetry:disableIf you change your mind and decide to share usage data with us, run this command:
npx fusionauth telemetry:enableIf you have a question or support issue regarding this client library, we'd love to hear from you.
If you have a paid edition with support included, please open a ticket in your account portal. Learn more about paid editions here.
Otherwise, please post your question in the community forum.
- Run the release script from the main branch:
./scripts/release.sh patch # or minor, major-
Create a Pull Request from the release branch to
main. -
After the PR is merged, tag the release, make sure they match:
./scripts/tag-release.sh <version> # e.g., 1.2.3- The GitHub Action will automatically build and publish to npm when the tag is pushed.
Bug reports and pull requests are welcome on GitHub.
To build this library locally:
git clone https://github.com/FusionAuth/fusionauth-node-cli &&
cd fusionauth-node-cli;
npm install &&
npm run build;
# now you can use it
npx fusionauth -h;To run commands directly from source during development (without installing globally):
npm run build && node dist/index.js <command> [options]
# Example:
node dist/index.js check:oauth-2-1 --key <api-key> --host http://localhost:9011To see examples of use: https://fusionauth.io/docs/extend/code/lambdas/testing
If you run this multiple times in a row against a local instance, the number of admin users may be incorrect until you re-index. See this issue for more.
The check:oauth-2-1 command validates your FusionAuth instance against OAuth 2.1 specification requirements (draft-ietf-oauth-v2-1-15).
# Check all applications across all tenants
fusionauth check:oauth-2-1 --key <api-key> --host <url>
# Check a specific application
fusionauth check:oauth-2-1 --key <api-key> --host <url> --application-id <app-id>
# Check all applications in a specific tenant
fusionauth check:oauth-2-1 --key <api-key> --host <url> --tenant-id <tenant-id>
# Enforce strict mode (fail on deprecated grants)
fusionauth check:oauth-2-1 --key <api-key> --host <url> --strict
# Output as JSON
fusionauth check:oauth-2-1 --key <api-key> --host <url> --json
# Show verbose per-application breakdown
fusionauth check:oauth-2-1 --key <api-key> --host <url> --verboseOnly applications with both the authorization_code and refresh_token grants enabled are checked.
REQUIRED (causes exit 1 if failed):
- PKCE enforcement set to "Required" on all applications (§7.5)
- Redirect URI validation set to "ExactMatch" — no wildcards (§4.1.3)
- HTTPS enforcement for all redirect URIs except localhost (§1.5)
- Refresh token rotation enabled via "OneTimeUse" usage policy (§4.3)
- Refresh token revocation on one-time token reuse enabled at the tenant level (§4.3)
- Tenant issuer properly configured — not default "acme.com"
WARNINGS (informational, does not cause exit 1):
- DPoP (sender-constrained tokens) available for applications (§1.4.3)
- Authorization code lifetime ≤ 600 seconds (§7.5)
- No deprecated grants enabled — Implicit, Password (§10); use
--strictto make this a failure
FusionAuth does not fully implement all OAuth 2.1 security requirements. The following gaps exist:
- Missing
issauthorization response parameter (§7.14) Theissauthorization response parameter for mix-up mitigation doesn't appear to be supported — use distinct redirect URIs per authorization server as a workaround (§7.14.2). See fusionauth-issues#1383.
For more information: