Skip to content

About

Resources

Security policy

Stars

1 star

Watchers

9 watching

Forks

Repository files navigation

FusionAuth CLI

The FusionAuth CLI is a command line tool for interacting with FusionAuth. It is written in Typescript and is available as an NPM package.

Requirements

  • 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)

Installation & usage

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-url is 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 own name field is used unless --name is 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-url is 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 own name field is used unless --name is 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 generation
    • fusionauth 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 FusionAuth
    • fusionauth kickstart:start - Run in the directory of a FusionAuth Docker image to run the image
    • fusionauth kickstart:stop - Run in the directory of a FusionAuth Docker image to stop the image
    • fusionauth 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 collection
    • fusionauth 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.

Telemetry and data collection

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:disable

If you change your mind and decide to share usage data with us, run this command:

npx fusionauth telemetry:enable

Questions and support

If 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.

Releasing

  1. Run the release script from the main branch:
./scripts/release.sh patch  # or minor, major
  1. Create a Pull Request from the release branch to main.

  2. After the PR is merged, tag the release, make sure they match:

./scripts/tag-release.sh <version>  # e.g., 1.2.3
  1. The GitHub Action will automatically build and publish to npm when the tag is pushed.

Contributing

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:9011

To see examples of use: https://fusionauth.io/docs/extend/code/lambdas/testing

Troubleshooting

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.

OAuth 2.1 Compliance

The check:oauth-2-1 command validates your FusionAuth instance against OAuth 2.1 specification requirements (draft-ietf-oauth-v2-1-15).

Usage

# 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> --verbose

What It Checks

Only 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 --strict to make this a failure

Known FusionAuth OAuth 2.1 Limitations

FusionAuth does not fully implement all OAuth 2.1 security requirements. The following gaps exist:

  1. Missing iss authorization response parameter (§7.14) The iss authorization 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:

About

Resources

Security policy

Stars

1 star

Watchers

9 watching

Forks

Releases

Packages

Used by

Contributors

Languages