Policy commands in the Permit CLI

Create the resources, actions, and roles of a Permit.io policy from your terminal. This reference is for developers who set up a policy in an environment without the Permit dashboard, for example in a script or a CI/CD pipeline.

Before you use these commands, install the Permit CLI and sign in with permit login. See Install and use the Permit CLI. Each command also accepts --api-key instead of the stored credentials. The commands change the policy of the environment you signed in to, or of the environment of the API key.

Choose a policy command

You have	Use
No policy yet, and you want a guided path to a first permission check	`permit init`
A list of resources, actions, and roles	`permit policy create simple`
A description of your app in plain language	`permit policy create ai`
A use case that matches a ready-made policy	`permit env template apply`
An OpenAPI spec for your API	`permit env apply openapi`

To confirm that any of these commands worked, open the Policy screen in the Permit dashboard. The Resources and Roles tabs list what the command created. To test a permission, run permit pdp check.

Start with the policy wizard

`permit init`

permit init starts a wizard that takes you through each step from configuring a policy to enforcing it in your app.

Flag	Description
`--api-key <string>`	The environment API key to create the policy with.

$ permit init --api-key permit_key

Create a policy from flags

`permit policy create simple`

permit policy create simple creates resources, actions, and roles in one command. Without flags, the command opens a table wizard that asks for each value.

Flag	Format	Description
`--resources <string...>`	`key:name@attribute1,attribute2`	A resource. `key` is the resource key, `name` is the display name, and the optional list after `@` is the resource attributes. Repeat the flag for each resource.
`--actions <string...>`	`key:description@attribute1,attribute2`	An action that the resources have. `description` and the attributes after `@` are optional. Repeat the flag for each action.
`--roles <string...>`	`role\|resource:action\|resource:action`	A role and its permissions. `role\|resource` without an action grants every action on the resource. Repeat the flag for each role.
`--api-key <string>`		The environment API key. Alias: `-k`.

Create a users and a posts resource, the create and read actions, and an admin and an editor role:

$ 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"

Generate a policy with AI

`permit policy create ai`

permit policy create ai generates a role-based access control (RBAC) policy from a description in natural language. The command starts an interactive prompt:

Describe your app and who can do what in it.
Review the resources, actions, roles, and permissions that the command shows as tables.
Answer the approval prompt. When you approve, the CLI creates the resources, roles, and permissions in your environment. When you reject, the CLI creates nothing.

Flag	Description
`--api-key <string>`	The environment API key.

$ permit policy create ai
Type your prompt...
A CRM SaaS application with different user types

Examples of descriptions:

A CRM SaaS application with different user types
A baseline WordPress policy with extended self-service capabilities
A file storage system with different levels of access
An internal ticket management system for production teams

Apply a policy template

A policy template is a ready-made policy for a use case, stored as a Terraform configuration.

`permit env template list`

permit env template list lists the policy templates you can apply.

Flag	Description
`--api-key <string>`	The API key of the environment to apply a template to.

$ permit env template list

`permit env template apply`

permit env template apply applies a policy template to your environment. By default, Permit runs the Terraform configuration on its servers, so you don't need Terraform on your machine. Without --template, the command asks you to choose a template.

Flag	Description
`--template <string>`	The name of the template to apply, from `permit env template list`. The command fails when the template doesn't exist.
`--local`	Runs Terraform on your machine instead of on Permit's servers. The command fails when Terraform isn't installed.
`--api-key <string>`	The API key of the environment to apply the template to.

$ permit env template apply --template mesa-verde-banking-dem

Create a policy from an OpenAPI spec

`permit env apply openapi`

permit env apply openapi reads an OpenAPI spec with x-permit extensions and creates the matching resources, actions, roles, relations, and derived roles in Permit. The command also creates a URL mapping for each mapped endpoint, so the PDP can check permissions by URL. See URL mapping checks.

Flag	Alias	Description
`--spec-file <string>`	`-f`	The path or HTTP URL of the OpenAPI spec file.
`--api-key <string>`	`-k`	The API key for Permit authentication.

# Run with spec file locally:
$ permit env apply openapi --spec-file ./api-spec.json

# Run with an API key and a spec file from a URL:
$ permit env apply openapi --api-key permit_key_... --spec-file https://example.com/openapi.json

OpenAPI extensions for Permit

Add these extensions to your OpenAPI spec to map it to a Permit policy.

Extension	Level	Description
`x-permit-resource`	Path	The resource key for the path. Required: the command skips paths without it.
`x-permit-action`	Operation (HTTP method)	The action key for the operation. Defaults to the HTTP method name, such as `get` or `post`.
`x-permit-role`	Operation	A top-level role that the operation allows.
`x-permit-resource-role`	Operation	A resource role that the operation allows.
`x-permit-relation`	Operation	An object that defines a relation between two resources.
`x-permit-derived-role`	Operation	An object that defines a role derivation.

This spec maps a blog API to the blog_post and blog_comment resources:

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

Object extension fields

x-permit-relation takes an object with these fields. The comments mark which fields are required:

{
	"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)
}

x-permit-derived-role takes an object with these fields. When you omit resource, the derived role applies to the resource of the path:

{
	"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)
}

URL mappings that the command creates

After the command creates the policy objects, the command creates a URL mapping rule for each endpoint that has x-permit-resource. Each rule has:

The URL path from the OpenAPI spec.
The HTTP method.
The resource from x-permit-resource.
The action from x-permit-action, or the HTTP method.

To check a request against these mappings, run permit pdp check-url.

Print the policies of an OPA server

`permit opa policy`

permit opa policy prints the policies loaded in a running Open Policy Agent (OPA) server. Use it to read the Rego that an OPA server runs, for example the OPA inside a PDP, without fetching the policy from Permit. The OPA server doesn't need to be connected to Permit.

Flag	Alias	Default	Description
`--server-url <string>`	`-s`	`http://localhost:8181`	The URL of the OPA server.
`--api-key <string>`		Stored credentials	The API key for the OPA server and the Permit environment, project, or workspace.

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

To reach the OPA server inside a PDP container, start the PDP with permit pdp run --opa 8181.

Policy commands in the Permit CLI

Choose a policy command

Start with the policy wizard

`permit init`

Create a policy from flags

`permit policy create simple`

Generate a policy with AI

`permit policy create ai`

Apply a policy template

`permit env template list`

`permit env template apply`

Create a policy from an OpenAPI spec

`permit env apply openapi`

OpenAPI extensions for Permit

Object extension fields

URL mappings that the command creates

Print the policies of an OPA server

`permit opa policy`

Contents

Need help?

Choose a policy command​

Start with the policy wizard​

permit init​

Create a policy from flags​

permit policy create simple​

Generate a policy with AI​

permit policy create ai​

Apply a policy template​

permit env template list​

permit env template apply​

Create a policy from an OpenAPI spec​

permit env apply openapi​

OpenAPI extensions for Permit​

Object extension fields​

URL mappings that the command creates​

Print the policies of an OPA server​

permit opa policy​

Related pages​

Contents

Need help?

Choose a policy command

Start with the policy wizard

`permit init`

Create a policy from flags

`permit policy create simple`

Generate a policy with AI

`permit policy create ai`

Apply a policy template

`permit env template list`

`permit env template apply`

Create a policy from an OpenAPI spec

`permit env apply openapi`

OpenAPI extensions for Permit

Object extension fields

URL mappings that the command creates

Print the policies of an OPA server

`permit opa policy`

Related pages