The Permit CLI is an open-source command-line tool that empowers developers to manage, test, and automate fine-grained access control across applications.
Designed with developer experience in mind, the CLI makes it easy to integrate Fine-Grained Authorization (FGA) and manage, test, and deploy access control logic across various systems, including OPA, OPAL, CEDAR, AVP, OpenFGA, and the Permit.io service.
- ⚙️ Create and manage authorization policies in projects and environments
- 🧪 Test and validate access control with audit log replays and end-to-end simulations
- 🚀 Run and interact with Policy Decision Points (PDPs) locally or remotely
- 🏗️ Automate policy operations in CI/CD with IaC and GitOps
- ✨ Generate policies from natural language using AI
- 🔐 Manage users, roles, and permissions directly from your terminal
💡 The CLI is fully open source and is built with Pastel, using TypeScript and a React-style architecture. Contributions welcome!
The Permit CLI is now available only via 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 user@permit.io --action list --resource transactions
Below is a categorized overview of all available Permit CLI commands:
permit login– Log in to your Permit.io account and authenticate your session.permit logout– Log out and clear stored credentials.
permit pdp run– Start a Permit PDP container using Docker.permit pdp check– Perform real-time authorization checks against the PDP.permit pdp stats– View performance metrics and audit statistics from your PDP instance.
-
Automate environment creation and management
permit env create– Create a new environment.permit env copy– Copy policies between environments.permit env delete– Delete an environment.permit env member– Add members to an environment and assign roles.permit env select– Switch active environment context.
-
permit policy create ai- Use natural language to generate and apply structured RBAC policies using AI.
-
permit init- Initialize the policy creation wizard.permit policy create simple- Use a table-style wizard or command-line arguments to define a policy with resources, actions, and roles.
-
permit env template list– List available policy templates to apply.permit env template apply– Apply a policy template to your current environment.
-
permit api sync user- Create or update a user with attributes and role assignments.permit api users list- List all users in your Permit.io account.permit api users assign- Assign a role to a user within a specified tenant.permit api users unassign- Remove a role assignment from a user.permit api create proxy- Create a new proxy config inside the Permit.io system.permit api list proxy- List all the proxy configs defined within an environment.
-
permit test run audit– Audit your policy decisions against recent logs. -
permit test generate e2e– Generate end-to-end policy test configurations and (optionally) test data.
-
permit pdp check-url- Check if a user has permission to access a specific URL. The command verifies URL-based permissions against the PDP using the Permit.io URL authorization API.
-
OpenAPI -x Extensions for Policy Configuration
permit env apply openapi- Create a full policy schema in Permit by reading an OpenAPI spec file and using-x-permitextensions, enabling the use of OpenAPI schema as a source of authorization policy configuration.
-
Sync policies to Git Repositories
permit gitops create github- Set up GitOps integration for a Permit environment using a GitHub repository.permit gitops env clone- Clone an environment or an entire project from a GitOps repository.
-
Extend Predefined Policies with Custom Rego (Open Policy Agent)
permit opa policy- Print policies from a running OPA (Open Policy Agent) instance.
You must log in to your Permit.io account to run commands.
The login command will take you to the browser to perform user authentication and then let you choose the workspace, project, and environment for future command runs.
Arguments (Optional):
--api-key <string>- store a Permit API key in your workstation keychain instead of running browser authentication--workspace <string>- predefined workspace key to skip the workspace selection step
Example:
$ permit loginThis command will log you out of your Permit account and remove the stored key from your workspace.
Example:
$ permit logoutThis collection of commands aims to improve the experience of working with the PDPs (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.
Arguments (Optional):
--api-key <string>- use a specific API key instead of the stored one--opa <number>- expose the OPA instance running in the PDP--dry-run- print the Docker command without executing it
Examples:
Run the PDP container
$ permit pdp runRun 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 the PDP 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.
Arguments (Required):
--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
Arguments (Optional):
--tenant <string>- the tenant to check the authorization for (default: default)--pdpurl <string>- the PDP URL to check the authorization against (default: http://localhost:7676)--user-attributes- additional user attributes to enrich the authorization check in the format:key1=value1,key2=value2-resource-attributes- additional resource attributes to enrich the authorization check in the formatkey1=value1,key2=value2
Example:
$ permit pdp check --user eventHandler --action update --resource Widget:dashboard-1-widgetUse this command to view statistics about your PDP's performance and usage. This is useful for monitoring and debugging your PDP instance.
Arguments (Optional):
--project-key <string>- The project key--environment-key <string>- the environment key--stats-url <string>- the URL of the PDP service. Default to the cloud PDP--api-key <string>- the API key for the Permit env, project, or Workspace--top- run stats in top mode (default: false)
Example:
$ permit pdp statsUse CLI commands to create, copy, and manage environments
This command creates a new environment in a specified project. This is useful for setting up new environments for development, testing, or production.
Arguments (Optional):
--api-key <string>- a Permit API key to authenticate the operation. If not provided, the command will use your stored credentials.--name <string>- the name of the new environment (will prompt if not provided)--env-key <string>- the key for the new environment (will be derived from name if not provided)--description <string>- the description of the new environment--customBranchName- customizes the GitOps branch name of this environment (default is set to the environment ID)--jwks <string>- JSON Web Key Set (JWKS) for frontend login, in JSON format--settings <string>- environment settings in JSON format
Examples:
$ permit env create --api-key permit_key --name "Staging" --description "Staging environment for testing"You can also create a complex environment with all options:
$ permit env create --api-key permit_key --name "Development" --envKey "dev" --description "Dev environment" --customBranchName "dev-branch" --jwks '{"ttl": 3600}' --settings '{"debug": true}'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 safely merge them into production after the tests.
Arguments (Required):
--api-key <string>- a Permit API key at the project level or higher to authenticate the operation
Arguments (Optional - Will prompt if not provided):
--from <string>- the source environment to copy the policies from--to <string>- the destination environment to copy the policies to--name <string>- the name of a new environment to copy the policies to--description <string>- the description of a new environment to copy the policies to--conflict-strategy <fail | overwrite>- the strategy to handle conflicts when copying policies (default: fail)
Example:
$ permit env copy --api-key permit_key --from staging --to production --conflict-strategy overwriteThis command deletes an existing environment.
:blub: Note: Use with caution: this operation cannot be undone.
Arguments (Optional):
--api-key <string>- a Permit API key to authenticate the operation. If not provided, the command will use your stored credentials.--environment-id <string>- the ID of the environment to delete (will prompt if not provided)--force <boolean>- skip confirmation prompts (default: false)
Examples:
$ permit env delete --api-key permit_key --environmentId env_456To force deletion without confirmation:
$ permit env delete --api-key permit_key --environmentId env_456 --forceNote: If you've authenticated via Permit’s login, the commands will use your current project context automatically.
This command will assign members to an 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.
Arguments (Required):
--api-key <string>(Required) - a Permit API key in project level or higher to authenticate the operation
Arguments (Optional - Will prompt if not provided):
--environment <string>- the environment to assign the roles to--project <string>- the project to assign the roles to--email <string>- the email of the member to assign the roles to--role <Owner | Editor | Member>- the role to assign to the member
Example:
$ permit env member --api-key permit_key --environment staging --project my-project --email gabriel@permit.io --role OwnerThis command lets you select a different active Permit.io environment. This is useful when you have multiple environments in your account and want to switch between them without logging out and logging in again.
Arguments (Required):
--api-key <string>- a Permit API key at the project level or higher to authenticate the operation. If not provided, the command will reauthenticate you in the browser.
Example:
$ permit env select --api-key permit_keyDefine and enforce policies programmatically within DevOps pipelines.
Export 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 exports all environment content (resources, roles, user sets, resource sets, condition sets) in the Permit Terraform provider format.
Arguments (Optional)
--api-key <string>- 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>- a file path where the exported HCL should be saved. If not provided, the output will be printed to the console.
Examples:
Using the Permit key -
$ permit env export terraform --api-key permit_key --file permit-config.tfWith the logged-in session -
$ permit env export terraform --file permit-config.tfPrint out the output to the console -
$ permit env export terraformUse natural language commands with AI to instantly set up and enforce fine-grained authorization policies.
Generate customized, ready-to-use policy structures using natural language
Allows you to create RBAC policies using natural language. Your descriptions will be converted using AI into structured Role-Based Access Control policies that can be applied to your Permit.io environment.
Arguments (Optional):
--api-key <string>- Your Permit.io API key. If not provided, the command will use your stored credentials.
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-templateThis command creates a full policy schema in Permit by reading an OpenAPI spec file and using -x-permit extensions to define resources, actions, roles, relations, and more. This enables developers to use their OpenAPI schema as a configuration source for their authorization policy.
--api-key <string>(Optional) - API key for Permit authentication--spec-file <string>(Optional) - Path to the OpenAPI file to read from. It could be a local path or an HTTP endpoint.
# Run with spec file locally:
$ permit env apply openapi --spec-file ./api-spec.json
# Run With API key:
$ permit env apply openapi --key permit_key_... --spec-file https://raw.githubusercontent.com/daveads/openapispec/main/blog-api.jsonThe command uses the following -x-permit extensions in your OpenAPI spec to map elements to the Permit policy:
x-permit-resource- The resource name to map the path to. This field is REQUIRED for a path to be mapped.
x-permit-action- Name of an action to map the HTTP method to. If not provided, the HTTP method name (get, post, etc.) will be used as the action.x-permit-role- Name of a top-level role that is ALLOWED for this particular operation.x-permit-resource-role- Name of a resource-level role that is ALLOWED for this particular operation.x-permit-relation- A JSON object defining a relation between resources.x-permit-derived-role- A JSON object defining role derivation rules.
openapi: 3.0.3
info:
title: 'Blog API with Permit Extensions'
version: '1.0.0'
paths:
/posts:
x-permit-resource: blog_post
get:
summary: List all posts
x-permit-action: list
x-permit-role: viewer
# ...
post:
summary: Create a new post
x-permit-action: create
x-permit-role: editor
x-permit-resource-role: post_creator
# ...
/posts/{postId}:
x-permit-resource: blog_post
get:
summary: Get a post by ID
x-permit-action: read
x-permit-role: viewer
# ...
put:
summary: Update a post
x-permit-action: update
x-permit-role: editor
# ...
delete:
summary: Delete a post
x-permit-action: delete
x-permit-role: admin
# ...
/posts/{postId}/comments:
x-permit-resource: blog_comment
get:
summary: Get comments for a post
x-permit-action: list
x-permit-role: viewer
x-permit-relation:
subject_resource: blog_comment
object_resource: blog_post
key: belongs_to_post
name: Belongs To Post
# ...
post:
summary: Add a comment to a post
x-permit-action: create
x-permit-role: commenter
x-permit-derived-role:
key: post_commenter
name: Post Commenter
base_role: viewer
derived_role: commenter
# ...Check this repo for a good example
For the more complex extensions that accept objects instead of strings, here's the expected structure:
{
"subject_resource": "string", // Required: The source resource in the relation
"object_resource": "string", // Required: The target resource in the relation
"key": "string", // Optional: Unique identifier for the relation (generated if not provided)
"name": "string" // Optional: Human-readable name (generated if not provided)
}{
"key": "string", // Optional: Unique identifier for the derived role
"name": "string", // Optional: Human-readable name for the derived role
"base_role": "string", // Required: The role that grants the derived role
"derived_role": "string", // Required: The role to be derived
"resource": "string" // Optional: The resource that the derived role applies to (defaults to the path's resource)
}After creating the policy elements based on the -x-permit extensions, the command will automatically create URL mappings in Permit. These mappings connect API endpoints to the appropriate resources and actions for runtime authorization checks.
For each endpoint with the required extensions, a mapping rule will be created with:
- URL path from the OpenAPI spec
- HTTP method
- Resource from
x-permit-resource - Action from
x-permit-actionor the HTTP method
This enables Permit to perform authorization checks directly against your API endpoints.
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 thekey. It has the alias asuser-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.- Only role the default tenant is assigned.
- Both the role and the tenant
- The resource Instance along with the role.
$ permit api sync user
--apiKey "YOUR_API_KEY" \
--key "892179821739812389327" \
--email "jane@coolcompany.com" \
--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 scopeProject.--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 listUse 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 toA377 --role <string>(Required) - role key to assign--tenant <string>(Required) - tenant key for the role assignment
$ permit api users assign --user user@example.com --role admin --tenant defaultUse 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 user@example.com --role admin --tenant defaultA 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 Keyname: 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 Keydescription: 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 keyresource: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|postsThis 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 john@example.com alice@example.com --resources document:123 folder:456
# Limit the number of logs processed
$ permit test run audit --max-logs 500This command allows you to create RBAC policies using natural language. It uses AI to convert your descriptions into structured Role-Based Access Control policies that can be applied to your Permit.io environment.
--api-key <string>(Optional) - Your Permit.io API key. If not provided, the command will use your stored credentials.
Example:
$ permit policy create ai
Type your prompt...
A CRM SaaS application with different user typesThis will start an interactive chat where you can describe your authorization requirements in natural language. The AI will convert your description into a structured RBAC policy with resources, roles, and permissions.
For example, you could describe:
- A CRM SaaS application with different user types
- Baseline WordPress policy with extended self-service capabilities
- A file storage system with varying levels of access
- Internal ticket management system for production teams
The AI will generate appropriate resources, roles, and permissions based on your description. The generated policy will be displayed in a table format showing the resources, actions, roles, and permissions. You can then approve or reject the generated policy.
If you approve the policy, the CLI will apply the policy to your Permit.io environment, creating all the resources, roles, and permissions defined in the policy.
Define resources, generate test users, and assign roles through a simple step-by-step flow.
Initialize the Permit policy wizard, which takes you through all the steps from configuring a policy to enforcing it in the application.
Arguments (Optional):
--api-key <string>: Use an environment API Key to create and store the policy.
Example:
$ permit init --api-key permit_key
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.
Arguments (Optional):
--api-key <string>- the Permit API key of the environment.--resources <string[]>- an array of resources in the format:key:name@attribute1,attribute2key- resource keyname- resource display name@attribute1,attribute2- a comma-separated list of attributes.
--actions <string[]>- an array of actions in the format:key:description@attribute1,attribute2key: action keydescription: action description@attribute1,attribute2: a comma-separated list of attributes.
--roles <string[]>- array of roles in the format:role|resource:action|resource:actionorrole|resource.role: role keyresource:action: the resource and the action to declare the permissions.
$ permit policy create simple \\
--api-key permit_key
--resources users:Users@department,role --resources posts:Posts@category \\
--actions create:Create --actions read:Read \\
--roles admin|users:create|posts:read --roles editor|postsUse pre-built policy templates to automate rule creation for different industries.
List all the available policy templates to apply to your environment.
Arguments (Optional)
--api-key <string>- API Key to be used for the environment to apply the Terraform template
Example:
$ permit env template listApplies a policy template to your current environment, which is useful for quickly setting up new environments with predefined configurations.
Note: The command uses the Terraform provider to apply the template, but a Terraform installation is not required.
Arguments (Optional)
--api-key <string>- API Key to be used for the environment to apply the policy template--local- to run the Terraform command locally (instead of on the server - will fail if Terraform isn’t installed)--template <string>- skips the template choice and applies the given template. Will fail if the template doesn’t exist.
Example:
$ permit env template apply --template mesa-verde-banking-demSimplifies the usage of Permit’s API, allowing you to perform most API actions directly through the CLI.
This command will replace User / Sync User in Permit. If the user already exists, 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.
Arguments (Optional):
--key <string>- a unique ID by which Permit will identify the user for permission checks. It has the aliasuser-id.--email <string>- user email. If synced, it will be unique inside the environment.--first_name <string>- user first name.--last_name <string>- user last name.--attributes <object>- user attributes used to enforce attribute-based access control policies.--roles- user roles. Can be given in 3 different formats:- The only role the default tenant is assigned.
- Both the role and the tenant
- The resource Instance along with the role.
--api-key <string>: a Permit API key to authenticate the operation. If not provided, the command will take the one you logged in with.
Example:
$ permit api sync user
--userid "892179821739812389327" \\
--email "jane@coolcompany.com" \\
--firstName "Jane" \\
--lastName "Doe" \\
--attributes "age:30" \\
--attributes "location:NY" \\
--roles "admin:stripe-inc" \\
--roles "developer" \\
--roles "project:123#developer"List all users in Permit.
Arguments (Optional):
--api-key <string>- your Permit API key--project-id <string>- your Permit project ID--env-id <string>- your Permit environment ID--expand-key- show full key values instead of truncated (default: false)--page <number>- page number for pagination (default: 1)--per-page <number>- number of items per page (default: 50)--role <string>- filter users by role--tenant <string>- filter users by tenant--all- fetch all pages of users (default: false)
Example:
$ permit api users list
--tenant default
--role admin
--allIn the example above, we fetch a list of all users with the admin role in the default tenant.
Assign a user to a specific role in Permit.
Arguments (Required):
--user <string>- user ID to assign role to--role <string>- role key to assign--tenant <string>- tenant key for the role assignment
Arguments (Optional):
--api-key <string>- your Permit API key--project-id <string>- Permit project ID--env-id <string>- Permit environment ID
Example:
$ permit api users assign --user user@example.com --role admin --tenant defaultRemove a role assignment from a user in Permit.
Arguments (Required):
--user <string>- user ID to unassign the role from--role <string>- role key to unassign--tenant <string>- tenant key for the role unassignment
Arguments (Optional):
--api-key <string>- your Permit API key--project-id <string>- Permit project ID--env-id <string>- Permit environment ID
Example:
$ permit api users unassign --user user@example.com --role admin --tenant defaultCreate a new proxy config inside the Permit.io system.
Arguments (Optional):
--api-Key <string>- your Permit API key.--secret <string>- Proxy config secret is set to enable the Permit Proxy to make proxied requests to the backend service.--key <string>- a unique ID by which Permit will identify the user for permission checks..--name <string>- The name of the proxy config, for example(e.g., Stripe API).--auth-mechanism <string>- Authentication mechanism used to inject the secret. One of: Bearer, Basic, Headers. Defaults to Bearer.--mapping-rules- Mapping rule must start with a valid HTTP method, then a URL, then a resource (e.g. "get|https://api.example.com|users"), then optionally: "|action|priority|{headers}|url_type".
Mapping rules can also be provided as individual Arguments (Optional - (Ignored if the mapping-rule arguments are present):
--mapping-rule-method <string>- Must be a valid HTTP method (get|put|post|delete|options|head|patch).--mapping-rule-url <string>- Must be a valid URL (e.g. https://api.example.com).--mapping-rule-resource <string>- Resource to match against the request (no leading slash).--mapping-rule-action <string>- Optional action name for the mapping rule.--mapping-rule-headers <array>- Optional list of headers, each as "Key:Value".--mapping-rule-priority <integer>- Optional priority (positive integer) for the mapping rule.--mapping-rule-url-type <string>- How to interpret the URL: "regex" or "none".
Examples:
$ permit api create proxy
--api-key "YOUR_API_KEY" \\
--secret "YOUR_SECRET" \\
--key "KEY" \\
--name "jhon" \\
--auth-mechanism "Bearer" \\
--mapping-rules "get|https://api.example.com|users|getUsers|10|{Authorization:Bearer abc,X-Custom:v7}|regex"Individual mapping rules:
$ permit api create proxy
--api-key "YOUR_API_KEY" \\
--secret "YOUR_SECRET" \\
--key "KEY" \\
--name "jhon" \\
--auth-mechanism "Bearer" \\
--mapping-rule-url https://foo.com \\
--mapping-rule-method post \\
--mapping-rule-resource myresource \\
--mapping-rule-headers "k1:v1" \\
--mapping-rule-action create \\
--mapping-rule-priority 10 \\
--mapping-rule-url-type regexList all the proxy configs defined within an environment.
Arguments (Optional):
--api-key <string>- your Permit API key--expand-key- show full key values instead of truncated (default: false)--page <number>- page number for pagination (default: 1)--per-page <number>- number of items per page (default: 30)--all- fetch all pages of users (default: false)
Example:
$ permit api list proxy
--api-key "YOUR_API_KEY" \\
--expand-key
--page 2
--per-page 50
--allIn the example above, we fetch a list of all proxies in the default environment.
This collection of commands helps you test and validate your authorization policies.
This command reads your recent authorization decision logs from the 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.
Arguments (Optional)
--api-key <string>- API Key to be used for test generation.--pdp-url <string>- URL of the PDP to verify against (default:http://localhost:7766)--time-frame <number>- Number of hours to fetch audit logs for (Between 6 and 72,default: 24)--source-pdp <string>- ID of the PDP to filter audit logs from--users <string[]>- Filter logs by specific users (can provide multiple)--resources <string[]>- Filter logs by specific resources (can provide multiple)--tenant <string>- Filter logs by specific tenant--action <string>- Filter logs by specific action--decision <allow | deny>- Filter logs by decision outcome--max-logs <number>- Maximum number of logs to process (useful for limiting large audit operations)
Examples:
Basic test against local PDP using the last 24 hours of audit logs:
$ permit test run audit --pdp-url <http://localhost:7766>
Testing against custom PDP URL with filters:
$ permit test run audit --pdpUrl <http://my-pdp.example.com:7766> --timeFrame 48 --action read --decision allow
Testing with multiple users and resources:
$ permit test run audit --users john@example.com alice@example.com --resources document:123 folder:456
Testing with a limit on the number of logs processed:
$ permit test run audit --max-logs 500
Simulate real-world user interactions and business flows to see how policies affect overall application behavior.
Generate end‑to‑end test configurations (and optionally test data) for your policy.
Arguments (Optional):
--api-key <string>- API Key to be used for test generation.--dry-run <boolean>- If set, generates test cases and mock data without making any changes in Permit.--models <string_array>- List of model names to generate tests for.default: RBAC.--path <string>- Filesystem path where the generated JSON config should be saved (recommended).
Note: All flags are optional. If you omit
--models, only the default RBAC model will be processed. If you omit--dry-run, real data and users will be created in Permit.
Examples:
Generate tests for the default RBAC model, and save the config to disk. Creates end‑to‑end tests for the RBAC model and writes the generated JSON config to logb.json
$ permit test generate e2e --models=RBAC --path=logb.jsonGenerate tests for RBAC, save the config, but don't apply changes (dry run). This is the same as above, but in dry‑run mode, so no changes are made in Permit.
$ permit test generate e2e --models=RBAC --path=logb.json --dry-runGenerate tests for the RBAC model without saving the config (dry run). This function generates test cases and mock data for RBAC, does not save a config file or apply changes, and prints to the terminal.
$ permit test generate e2e --models=RBAC --dry-runGenerate and apply tests for the RBAC model with default settings. Runs end‑to‑end test generation for RBAC using real data (no dry run) and without writing a config file, and prints to the terminal.
$ permit test generate e2e --models=RBACDefine and enforce API authorization policies using OpenAPI specifications for a smooth API integration.
Map API endpoints to policies using simple configurations and FastAPI decorators
Check if a user has permission to access a specific URL. The command verifies URL-based permissions against the PDP using the Permit.io URL authorization API.
Arguments (Required):
--user <string>- the user id to check permissions for (Required)--url <string>- the URL to check permissions for (Required)
Arguments (Optional):
--method <string>- the HTTP method to check permissions for (default:GET)--tenant <string>- the tenant to check permissions for (default:default)--user-attributes <string>- additional user attributes to enrich the authorization check in the formatkey1:value1,key2:value2. Can be specified multiple times.--pdp-url <string>- the PDP URL to check authorization against (default: Cloud PDP)--api-key <string>- the API key for the Permit env, project or Workspace
Examples:
Basic URL permission check:
$ permit pdp check-url --user john@example.com --url https://api.example.com/ordersCheck with specific HTTP method and tenant:
$ permit pdp check-url --user john@example.com --url https://api.example.com/orders --method POST --tenant acme-corp
Check with user attributes:
$ permit pdp check-url --user john@example.com --url https://api.example.com/orders --user-attributes role:admin --user-attributes department:sales
Check against local PDP:
$ permit pdp check-url --user john@example.com --url https://api.example.com/orders --pdp-url http://localhost:7766
Define access control rules directly within OpenAPI specifications.
Creates a full policy schema in Permit by reading an OpenAPI spec file and using -x-permit extensions to define resources, actions, roles, relations, and more. This enables developers to use their OpenAPI schema as a configuration source for their authorization policy.
Arguments (Optional):
--api-key <string>- API key for Permit authentication--spec-file <string>- Path to the OpenAPI file to read from. It could be a local path or an HTTP endpoint.
Example:
Run with spec file locally:
$ permit env apply openapi --spec-file ./api-spec.json
Run with API key:
$ permit env apply openapi --key permit_key --spec-file https://raw.githubusercontent.com/daveads/openapispec/main/blog-api.json
OpenAPI Extensions:
The command uses the following -x-permit extensions in your OpenAPI spec to map elements to the Permit policy:
Path or Endpoint Level Extensions (Required):
x-permit-resource- The name of the resource to which you want to map the path.
Operation Level Extensions (HTTP Method Level):
x-permit-action- Name of an action to map the HTTP method to. If not provided, the HTTP method name (get, post, etc.) will be used as the action.x-permit-role- Name of a top-level role that is ALLOWED for this particular operation.x-permit-resource-role- Name of a resource-level role that is ALLOWED for this particular operation.x-permit-relation- A JSON object defining a relation between resources.x-permit-derived-role- A JSON object defining role derivation rules.
Example: OpenAPI Spec with Permit Extensions
openapi: 3.0.3
info:
title: 'Blog API with Permit Extensions'
version: '1.0.0'
paths:
/posts:
x-permit-resource: blog_post
get:
summary: List all posts
x-permit-action: list
x-permit-role: viewer
# ...
post:
summary: Create a new post
x-permit-action: create
x-permit-role: editor
x-permit-resource-role: post_creator
# ...
/posts/{postId}:
x-permit-resource: blog_post
get:
summary: Get a post by ID
x-permit-action: read
x-permit-role: viewer
# ...
put:
summary: Update a post
x-permit-action: update
x-permit-role: editor
# ...
delete:
summary: Delete a post
x-permit-action: delete
x-permit-role: admin
# ...
/posts/{postId}/comments:
x-permit-resource: blog_comment
get:
summary: Get comments for a post
x-permit-action: list
x-permit-role: viewer
x-permit-relation:
subject_resource: blog_comment
object_resource: blog_post
key: belongs_to_post
name: Belongs To Post
# ...
post:
summary: Add a comment to a post
x-permit-action: create
x-permit-role: commenter
x-permit-derived-role:
key: post_commenter
name: Post Commenter
base_role: viewer
derived_role: commenter
# ...A more detailed example is available here
For the more complex extensions that accept objects instead of strings, here's the expected structure:
- Object Structure:
x-permit-relation
{
"subject_resource": "string", // Required: The source resource in the relation
"object_resource": "string", // Required: The target resource in the relation
"key": "string", // Optional: Unique identifier for the relation (generated if not provided)
"name": "string" // Optional: Human-readable name (generated if not provided)
}
- Object Structure:
x-permit-derived-role
{
"key": "string", // Optional: Unique identifier for the derived role
"name": "string", // Optional: Human-readable name for the derived role
"base_role": "string", // Required: The role that grants the derived role
"derived_role": "string", // Required: The role to be derived
"resource": "string" // Optional: The resource that the derived role applies to (defaults to the path's resource)
}
Extend and customize authorization policies with GitOps flows and custom Rego logic.
Export, version, and manage authorization policies as code: all through CLI commands
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.
Arguments (Required)
--inactive <boolean>- set the environment to inactive after configuring GitOps (default:false)
Example:
gitops create github --inactive true
This clones the environment or the complete project from the active GitOps repository.
Arguments (Optional)
--api-key <string>- The API key to select the project. The API Key is of the scopeProject.--dry-run- Instead of executing the code, it displays the command to be executed.--project- Instead of selecting an environment branch to clone, it performs the standard clone operation.
Use the CLI to modify and fine-tune Open Policy Agent (OPA) Rego policies while maintaining system stability.
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.
After creating the policy elements based on the -x-permit extensions, the command will automatically create URL mappings in Permit. These mappings connect API endpoints to the appropriate resources and actions for runtime authorization checks.
For each endpoint with the required extensions, a mapping rule will be created with:
- URL path from the OpenAPI spec
- HTTP method
- Resource from
x-permit-resource - Action from
x-permit-actionor the HTTP method
This enables Permit to perform authorization checks directly against your API endpoints.
Arguments (Optional)
--api-key <string>- the API key to authenticate the operation--server-url <string>- the URL of the OPA server to fetch the policies from (default: http://localhost:8181)
Example:
$ permit opa policy --server-url <http://localhost:8181> --api-key permit_keyPermit 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.
- Run
npm install - Run
npm run dev - Use the CLI with the following convention
node ./dist/cli.js command [options]
The project uses TypeScript definitions generated from Permit.io's OpenAPI specs. These definitions are automatically updated weekly via GitHub Actions, but you can also update them locally:
npm run update-typesThis will download the latest OpenAPI specifications from Permit.io's API endpoints and generate updated TypeScript definitions.
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 enforces a UT coverage level of >90% for the main code.
The CLI uses vitest as its test framework. It also uses ink-testing-library to render the Ink components.
- Run
npm run testsfor testing and coverage
We would love to chat with you about the Permit CLI. Join our Slack community to chat about access control, open-source, and authorization.
You can raise questions and request features be added to the roadmap in our GitHub discussions and report issues in **GitHub issues.**
Like our project? Give 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:
- 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.