Install and use the Permit CLI

Install the Permit CLI, sign in, and run your first permission check from the terminal. This page is for developers who want to manage Permit.io policies, environments, users, and policy decision points (PDPs) from a terminal or a CI/CD pipeline. It ends with an index of every command and the page that documents it.

The Permit CLI is open source. The code is in the permitio/permit-cli repository on GitHub.

Prerequisites

• Node.js version 22 or later, with npm.
• A Permit.io account. Sign up at app.permit.io.
• For the PDP commands that run a container: Docker.

Install the Permit CLI

Install the @permitio/cli package globally with npm:

npm install -g @permitio/cli

The package adds the permit command to your path.

Sign in to Permit

Most commands call the Permit API, so they need your credentials. Run permit login once before you use them, or pass --api-key to each command.

permit login

permit login opens your browser to sign in to Permit. After you sign in, the CLI asks you to choose a workspace, a project, and an environment. Later commands run against that environment.

Flag	Alias	Description
--api-key <string>	-k	Sign in with a Permit API key instead of the browser.
--workspace <string>		The workspace key to use, which skips the workspace selection step.
--region <string>	-r	The Permit region: us or eu. Defaults to us.

$ permit login

The CLI stores the credentials in your operating system's keychain.

permit logout

permit logout signs you out and deletes the stored credentials from your keychain.

$ permit logout

Run a command

Every command follows this form:

$ permit [command] [options]

Flags use kebab-case, for example --api-key and --pdp-url. To list the commands and flags of a command group, add --help, for example permit pdp check --help.

Confirm that the CLI works

After you sign in, check a permission against the Cloud PDP of your environment. Replace the user, action, and resource with ones from your policy:

$ permit pdp check --user user@permit.io --action list --resource transactions

The CLI prints ALLOWED or DENIED. An error instead of a decision means the CLI isn't signed in, or the Permit API is out of reach. For all permit pdp check flags, see PDP commands.

Command index

Policy decision point (PDP) commands

Command	What it does
permit pdp run	Starts a PDP Docker container for your environment.
permit pdp check	Checks whether a user can perform an action on a resource.
permit pdp check-url	Checks whether a user can call a URL with an HTTP method.
permit pdp stats	Shows statistics about a PDP.

Environment and Terraform commands

Command	What it does
permit env create	Creates an environment.
permit env copy	Copies an environment's policy to a new or existing environment.
permit env delete	Deletes an environment.
permit env member	Invites a member to an environment with a role.
permit env select	Changes the active environment.
permit env export terraform	Exports an environment as a Terraform HCL file.

Policy commands

Command	What it does
permit init	Starts a wizard that takes you from a policy to an enforced permission check.
permit policy create simple	Creates resources, actions, and roles from flags or a table wizard.
permit policy create ai	Generates a role-based access control (RBAC) policy from a natural language description.
permit env template list	Lists the policy templates.
permit env template apply	Applies a policy template to the active environment.
permit env apply openapi	Creates a policy from an OpenAPI spec with x-permit extensions.
permit env apply trino	Creates resources from the catalogs, schemas, and tables of a Trino cluster.
permit opa policy	Prints the policies loaded in a running Open Policy Agent (OPA) server.

API commands

Command	What it does
permit api sync user	Creates or updates a user with attributes and role assignments.
permit api users list	Lists the users in an environment.
permit api users assign	Assigns a role to a user in a tenant.
permit api users unassign	Removes a role assignment from a user.
permit api create proxy	Creates a Permit Proxy configuration.
permit api list proxy	Lists the Permit Proxy configurations in an environment.

Policy testing commands

Command	What it does
permit test run audit	Runs the checks from recent audit logs against a PDP and lists the decisions that differ.
permit test generate e2e	Generates end-to-end test cases, and optionally test data, for your policy.
permit test generate code-sample	Generates a Jest, Vitest, or pytest file that runs the generated test cases.

GitOps commands

Command	What it does
permit gitops create github	Connects a GitHub repository to an environment for GitOps.
permit gitops env clone	Clones an environment branch or the whole policy repository.

Next steps

• Run a PDP and check permissions from the CLI
• Create a policy from the CLI
• Manage environments and export them to Terraform
• Manage policy as code with the Terraform provider
• Manage policy with GitOps