The Permit CLI is an open-source command-line utility that empowers developers with everything related to Fine-Grained Authorization (FGA) and Identity and Access Management (IAM). It is a one-stop solution for handling all your authorization needs, seamlessly integrating with tools like OPA, OPAL, CEDAR, AVP, OpenFGA, and the Permit.io service.

💡 Permit CLI is fully open-source and actively accepts contributions of many cool features. Leverage your open-source game by contributing and giving it a ⭐

Permit CLI is now available only via the npm and requires a Node.js installation to run

npm install -g @permitio/cli

All the commands in the CLI are available via the permit command in the following convention:

$ permit [command] [options]

For example:

$ permit pdp check --user [email protected] --action list --resource transactions

• login - login to your Permit.io account

• logout - logout from Permit.io

• pdp - a collection of commands to work with Permit's Policy Decision Point (PDP)

  • run - print a docker command to run your Permit PDP
  • check - perform an authorization check against the PDP
  • stats - view statistics about your PDP's performance and usage

• env - a collection of commands to manage Permit policy environments

  • copy - copy a Permit environment with its policies to another environment
  • create - create a new environment in a project
  • delete - delete an existing environment
  • member - add and assign roles to members in Permit
  • select - select a different active Permit.io environment
  • export - export environment configurations to different formats
  • template - manage and apply policy and authorization templates in an environment
    • list - list all the available policy templates
    • apply - apply an environment template to your current environment

• opa - a collection of commands for better OPA experience

  • policy - print the available policies of an active OPA instance

• gitops create github - configure Permit environment to use GitOps flow

• gitops env clone - clone a environment of the gitops repository or a complete project.

• api - direct access to Permit.io's API functionality

  • users - manage users in your Permit.io account
    • list - list all users in your Permit.io account
    • assign - assign a user to a specific role in your Permit.io account
    • unassign - remove a role assignment from a user in your Permit.io account
  • sync - To sync the data from CLI to permit.io
    • user - To update or create a user from the CL

• policy create simple - Create a simple policy Table

• test - commands for testing authorization policies

  • run audit - test PDP against past authorization decisions

After installing the CLI, you must authenticate to run commands against your Permit.io account.

The login command will take you to the browser to perform user authentication and then let you choose the workspace, project, and environment to for future command runs.

• --key <string> (Optional) - store a Permit API key in your workstation keychain instead of running browser authentication
• --workspace <string> (Optional) - predefined workspace key to skip the workspace selection step

$ permit login

This command will log you out from your Permit account and remove the stored key from your workspace.

permit logout

This collection of commands aims to improve the experience of working with Policy Decision Points (PDP) such as the Permit PDP or Open Policy Agent.

Use this command to run a Permit PDP Docker container configured with your Permit.io account details. The command will start the container in detached mode and display the container ID and name.

• --opa <number> (Optional) - expose the OPA instance running in the PDP
• --dry-run (Optional) - print the Docker command without executing it
• --api-key <string> (Optional) - use a specific API key instead of the stored one

# Run the PDP container
$ permit pdp run

# Run the PDP container with OPA exposed on port 8181
$ permit pdp run --opa 8181

# Print the Docker command without running the container
$ permit pdp run --dry-run

# Run with a specific API key
$ permit pdp run --api-key your_api_key

Use this command to perform an authorization check against the PDP. The command will take the user, action, and resource (and some other enrichment arguments) as options and return the decision.

• --user <string> - the user id to check the authorization for
• --action <string> - the action to check the authorization for
• --resource <string> - the resource to check the authorization for
• --tenant <string> (Optional) - the tenant to check the authorization for (default: default)
• --pdpurl <string> (Optional) - the PDP URL to check the authorization against (default: http://localhost:7676)
• --user-attributes (Optional) - additional user attributes to enrich the authorization check in the format key1=value1,key2=value2
• --resource-attributes (Optional) - additional resource attributes to enrich the authorization check in the format key1=value1,key2=value2

$ permit  pdp check --user eventHandler --action update --resource Widget:dashboard-1-widget

Use this command to view statistics about your PDP's performance and usage. This is useful for monitoring and debugging your PDP instance.

• --project-key <string> (Optional) - the project key
• --environment-key <string> (Optional) - the environment key
• --stats-url <string> (Optional) - the URL of the PDP service. Default to the cloud PDP
• --api-key <string> (Optional) - the API key for the Permit env, project or Workspace
• --top (Optional) - run stats in top mode (default: false)

$ permit pdp stats

This collection of commands will enable you to automate SDLC operations for Fine-Grained Authorization with Permit.io

Developers and CI pipelines can use this command to enable secure blue-green deployment in the Software Development Lifecycle (SDLC). The command will get the source and destination environments as options and copy the policies from one to another. This will let you run your tests again in a non-production environment and merge it safely into production after the tests.

• --key <string> (Required) - a Permit API key in project level or higher to authenticate the operation
• --from <string> (Optional) - the source environment to copy the policies from (will prompt if not provided)
• --to <string> (Optional) - the destination environment to copy the policies to (will prompt if not provided)
• --name <string> (Optional) - the name of a new environment to copy the policies to (will prompt if not provided)
• --description <string> (Optional) - the description of a new environment to copy the policies to (will prompt if not provided)
• --conflict-strategy <fail | overwrite> (Optional) - the strategy to handle conflicts when copying policies (default: fail)

$ permit env copy --key permit_key_.......... --from staging --to production --conflict-strategy overwrite

This command creates a new environment in a specified project. This is useful for setting up new environments for development, testing, or production.

• apikey (Optional) - a Permit API key to authenticate the operation. If not provided, the command will use your stored credentials.
• name (Optional) - the name of the new environment (will prompt if not provided)
• envKey (Optional) - the key for the new environment (will be derived from name if not provided)
• description (Optional) - the description of the new environment
• jwks <string> (Optional) - JSON Web Key Set (JWKS) for frontend login, in JSON format
• settings <string> (Optional) - environment settings in JSON format

$ permit env create --key permit_key_.......... --name "Staging" --description "Staging environment for testing"

You can also create a complex environment with all options:

$ permit env create --apiKey permit_key_.......... --name "Development" --envKey "dev" --description "Dev environment" --customBranchName "dev-branch" --jwks '{"ttl": 3600}' --settings '{"debug": true}'

This command deletes an existing environment. Use with caution as this operation cannot be undone.

• key (Optional) - a Permit API key to authenticate the operation. If not provided, the command will use your stored credentials.
• environmentId (Optional) - the ID of the environment to delete (will prompt if not (provided)
• force (Optional) - skip confirmation prompts (default: false)

$ permit env delete --key permit_key_.......... --environmentId env_456

Or to force deletion without confirmation:

$ permit env delete --key permit_key_.......... --environmentId env_456 --force

Note: If you've authenticated via permit login, the commands will use your current project context automatically.

This command will assign members to environment with the roles you specify. This is useful for managing the access control of your team members in the Permit.io environment.

This command can run in the CI after creating a new environment for development or testing to assign the roles to the team members who need to access the environment.

• --key <string> (Required) - a Permit API key in project level or higher to authenticate the operation
• --environment <string> (Optional) - the environment to assign the roles to (will prompt if not provided)
• --project <string> (Optional) - the project to assign the roles to (will prompt if not provided)
• --email <string> (Optional) - the email of the member to assign the roles to (will prompt if not provided)
• --role <Owner | Editor | Member> (Optional) - the role to assign to the member (will prompt if not provided)

$ permit env member --key permit_key_.......... --environment staging --project my-project --email [email protected] --role Owner

This command will let you select a different active Permit.io environment. This is useful when you have multiple environments in your account and you want to switch between them without logging out and logging in again.

• --key <string> (Optional) - a Permit API key in project level or higher to authenticate the operation. If not provided, the command will reauthenticate you in the browser.

$ permit env select --key permit_key_.........

This command exports your Permit environment configuration as a Terraform HCL file. This is useful for users who want to start working with Terraform after configuring their Permit settings through the UI or API. The command export all environment content (resources, roles, user sets, resource sets, condition sets) in the Permit Terraform provider format.

Options

• --key <string> (Optional) - a Permit API key to authenticate the operation. If not provided, the command will use the AuthProvider to get the API key you logged in with.

• --file <string> (Optional) - a file path where the exported HCL should be saved. If not provided, the output will be printed to the console.

$ permit env export terraform --key permit_key_.......... --file permit-config.tf

$ permit env export terraform --file permit-config.tf

permit env export terraform

This collection of commands helps you manage and apply policy and authorization templates in an environment.

Use this command to list all the available policy templates to apply to your environment.

• --api-key <string> (Optional) - API Key to be used for the environment to apply the terraform template

$ permit env template list

Use this command to apply a policy template to your current environment. This is useful for quickly setting up new environments with predefined configurations. The command is using the Terraform provider to apply the template, but it's not required to have Terraform installed.

• --api-key <string> (Optional) - API Key to be used for the environment to apply the policy template
• --local (Optional) - to run the Terraform command locally instead of the server (will fail if Terraform is not installed)
• --template <string> (Optional) - skips the template choice and applies the given template. It will fail if the template does not exist

$ permit env template apply --template my-template

This collection of commands aims to create new experiences for developers working with Open Policy Agent (OPA) in their projects.

This command will print the available policies of an active OPA instance. This is useful when you want to see the policies in your OPA instance without fetching them from the OPA server.

• --server-url <string> (Optional) - the URL of the OPA server to fetch the policies from (default: http://localhost:8181)
• --api-key <string> (Optional) - the API key to authenticate the operation

$ permit opa policy --server-url http://localhost:8181 --api-key permit_key_..........

This command will Replace User / Sync User in the system. If the user already exits, it will update the user with the new data. If the user does not exist, it will create a new user with the provided data.

• api_key <string>(optional) : a Permit API key to authenticate the operation. If not provided, the command will take the one you logged in with.

• key <string> : A unique id by which Permit will identify the user for permission checks. If not given in the argument the interactive CLI is open to retrive the key. It has the alias as user-id.

• email <string>: The email of the user. If synced, will be unique inside the environment.

• first_name <string> : First name of the user.

• last_name <string> : Last name of the user.

• attributes <object> : Arbitrary user attributes that will be used to enforce attribute-based access control policies.

• roles : roles of the user. Given in 3 different formats.

  1. Only role the default tenant is assigned.
  2. Both the role and the tenant
  3. The resource Instance along with the role.

$ permit api sync user
  --apiKey "YOUR_API_KEY" \
  --userid "892179821739812389327" \
  --email "[email protected]" \
  --firstName "Jane" \
  --lastName "Doe" \
  --attributes  "age:30" \
  --attributes "location:NY" \
  --roles "admin:stripe-inc" \
  --roles "developer" \
  --roles "project:123#developer"

This command will configure your Permit environment to use the GitOps flow with GitHub. This is useful when you want to manage your policies in your own Git repository and extend them with custom policy code.

• --key <string> (Optional) - a Permit API key to authenticate the operation. If not provided, the command will take the one you logged in with.
• --inactive <boolean> (Optional) - set the environment to inactive after configuring GitOps (default: false)

This clones the environment or the complete project from the active gitops repository.

• --api-key <string> (Optional) - The API key to select the project. The API Key is of the scope Project.
• --dry-run (Optional) - Instead of executing the code it just displays the command to be executed.
• --project (Optional) - Instead of selecting an environment branch to clone it does the standard clone operation.

This collection of commands provides direct access to Permit.io's API functionality.

This collection of commands helps you manage users in your Permit.io account.

Use this command to list all users in your Permit.io account.

• --api-key <string> (Optional) - your Permit.io API key
• --project-id <string> (Optional) - Permit.io Project ID
• --env-id <string> (Optional) - Permit.io Environment ID
• --expand-key (Optional) - show full key values instead of truncated (default: false)
• --page <number> (Optional) - page number for pagination (default: 1)
• --per-page <number> (Optional) - number of items per page (default: 50)
• --role <string> (Optional) - filter users by role
• --tenant <string> (Optional) - filter users by tenant
• --all (Optional) - fetch all pages of users (default: false)

$ permit api users list

Use this command to assign a user to a specific role in your Permit.io account.

• --api-key <string> (Optional) - your Permit.io API key
• --project-id <string> (Optional) - Permit.io Project ID
• --env-id <string> (Optional) - Permit.io Environment ID
• --user <string> (Required) - user ID to assign role to
• --role <string> (Required) - role key to assign
• --tenant <string> (Required) - tenant key for the role assignment

$ permit api users assign --user [email protected] --role admin --tenant default

Use this command to remove a role assignment from a user in your Permit.io account.

• --api-key <string> (Optional) - your Permit.io API key
• --project-id <string> (Optional) - Permit.io Project ID
• --env-id <string> (Optional) - Permit.io Environment ID
• --user <string> (Required) - user ID to unassign role from
• --role <string> (Required) - role key to unassign
• --tenant <string> (Required) - tenant key for the role unassignment

$ permit api users unassign --user [email protected] --role admin --tenant default

A simple policy table creation wizard with the resources, actions and roles. You can provide resources, actions, and roles as arguments or enter them interactively.

• api-key <string> Optional: The Permit API key of the environment.

• resources <string[]> (Optional) : Array of resources in the format: "key:name@attribute1,attribute2"

  • key: Resource Key
  • name: Resource display Name
  • @attribute1,attribute2 : comma-seperated list of attributes.

• actions <string[]> (Optional) : Array of actions in the format: "key:description@attribute1,attribute2"

  • key : Action Key
  • description : Action description
  • @attribute1,attribute2: Comma-sperated list of attributes.

• roles <string[]> (Optional) : Array of roles in the format: "role|resource:action|resource:action" or "role|resource"

  • role: Role key
  • resource:action: The resource and the action to declare the permissions.

$ permit policy create simple \
  --api-key permit_key_abc123
  --resources users:Users@department,role --resources posts:Posts@category \
  --actions create:Create --actions read:Read \
  --roles admin|users:create|posts:read --roles editor|posts

This collection of commands helps you test and validate your authorization policies.

This command reads your recent authorization decision logs from Permit API and runs the same checks against a PDP instance to verify consistency between environments.

The command is particularly useful for validating that policy changes don't break existing authorization behavior and for testing a new PDP instance against production decisions.

• --pdp-url <string> (Optional) - URL of the PDP to verify against (default: http://localhost:7766)
• --time-frame <number> (Optional) - Number of hours to fetch audit logs for (between 6 to 72, default: 24)
• --source-pdp <string> (Optional) - ID of the PDP to filter audit logs from
• --users <string[]> (Optional) - Filter logs by specific users (can provide multiple)
• --resources <string[]> (Optional) - Filter logs by specific resources (can provide multiple)
• --tenant <string> (Optional) - Filter logs by specific tenant
• --action <string> (Optional) - Filter logs by specific action
• --decision <allow | deny> (Optional) - Filter logs by decision outcome
• --max-logs <number> (Optional) - Maximum number of logs to process (useful for limiting large audit operations)

# Basic test against local PDP using last 24 hours of audit logs
$ permit test run audit
$ permit test run audit --pdp-url http://localhost:7766
# Test against custom PDP URL with filters
$ permit test run audit --pdpUrl http://my-pdp.example.com:7766 --timeFrame 48 --action read --decision allow

# Test with multiple users and resources
$ permit test run audit --users [email protected] [email protected] --resources document:123 folder:456

# Limit the number of logs processed
$ permit test run audit --max-logs 500

Permit CLI is based on Pastel, a library for building CLI applications using React-like syntax. The project is written in TypeScript and uses tsc to run the CLI commands in development.

• Checkout this repo
• Run npm install
• Run npm run dev
• Use the CLI with the following convention node ./dist/cli.js command [options]

To add a new command, you need to create a new file in the src/commands directory with the command name. The project is using the Pastel library to create the CLI commands. You can find the documentation here

For a detailed command contribution guide, please refer to the CONTRIBUTING.md file.

Permit CLI enforce UT coverage level of >90% for the code in main.

The CLI uses vitest as its test framework. It also uses ink-testing-library to render the Ink components.

• run npm run tests for testing and coverage

We would love to chat with you about Pernut CKU. Join our Slack community to chat about fine-grained authorization, open-source, realtime communication, tech, or anything else!

You can raise questions and ask for features to be added to the road-map in our Github discussions, report issues in Github issues

If you like our project, please consider giving us a ⭐️

We would love for you to contribute to this project and help make it even better than it is today! 💎

As a contributor, here are the guidelines we would like you to follow:

• Code of Conduct
• Question or Problem?
• Issues and Bugs
• Feature Requests
• New Commands Guidelines

• Check out OPAL - the best way to manage Open Policy Agent (OPA), Cedar, and OpenFGA in scale.
• Check out Cedar-Agent, the easiest way to deploy & run AWS Cedar.