Skip to main content

Permit CLI Reference

The Permit CLI is a command-line tool that provides integrated access to Permit.io's functionality. From policy management and testing to user synchronization and GitOps workflows, the CLI enables developers to automate and streamline their authorization workflows.

Installation​

Install the Permit CLI globally using npm:

npm install -g @permitio/cli

Verify the installation:

permit

Authentication​

Before using the CLI, you need to authenticate with your Permit.io account:

permit login

This will open your browser for authentication. After successful login, your credentials are stored locally for future use.

Log out and clear stored credentials:

permit logout

Core Commands​

Policy Management​

The CLI provides several methods for creating and managing authorization policies, from AI-powered generation to simple template-based creation.

Create Policies with AI​

Generate RBAC policies using natural language descriptions:

permit policy create ai

The AI will guide you through describing your authorization requirements and generate structured policies with resources, roles, and permissions.

Example:

$ permit policy create ai
Type your prompt...
A CRM SaaS application with different user types: admins who can do everything, managers who can manage their team's data, and users who can only view their own data.

Simple Policy Creation​

Create policies quickly with predefined resources, actions, and roles:

permit policy create simple \
  --resources "document:Document@category,status" \
  --actions "create:Create Document" "read:Read Document" "update:Update Document" "delete:Delete Document" \
  --roles "admin|document:create|document:read|document:update|document:delete" \
  --roles "editor|document:create|document:read|document:update" \
  --roles "viewer|document:read"

Options:

  • --api-key <string> - Permit API key for the environment
  • --resources <string[]> - Array of resources in format: key:name@attribute1,attribute2
  • --actions <string[]> - Array of actions in format: key:description
  • --roles <string[]> - Array of roles in format: role|resource:action|resource:action

Interactive Policy Wizard​

Initialize the policy creation wizard for step-by-step policy setup:

permit init

This command guides you through creating a complete authorization policy interactively, similar to the web interface workflow.

Options:

  • --api-key <string> - Use an environment API key to create and store the policy

User Management​

Manage users, their attributes, and role assignments across your authorization system.

Sync Users​

Create or update users in your Permit environment:

permit api sync user \
  --key "john@example.com" \
  --email "john@example.com" \
  --first_name "John" \
  --last_name "Doe" \
  --attributes "department:engineering" \
  --attributes "level:senior" \
  --roles "admin:default" \
  --roles "developer"

Options:

  • --key <string> - Unique user identifier (required)
  • --email <string> - User email address
  • --first_name <string> - User's first name
  • --last_name <string> - User's last name
  • --attributes <object> - User attributes for ABAC policies
  • --roles - Role assignments in formats:
    1. role - Default tenant role
    2. role:tenant - Specific tenant role
    3. resource:instance#role - Resource instance role
  • --api-key <string> - Permit API key (optional)

List Users​

Retrieve all users in your environment:

permit api users list

Options:

  • --api-key <string> - Your Permit API key
  • --project-id <string> - Project ID
  • --env-id <string> - Environment ID
  • --role <string> - Filter by role
  • --tenant <string> - Filter by tenant
  • --all - Fetch all pages
  • --page <number> - Page number (default: 1)
  • --per-page <number> - Items per page (default: 50)

Assign/Unassign Roles​

Manage user role assignments:

# Assign a role
permit api users assign --user "john@example.com" --role "admin" --tenant "default"

# Unassign a role
permit api users unassign --user "john@example.com" --role "admin" --tenant "default"

Policy Testing​

Validate your authorization policies through testing and audit verification.

Audit Log Replay​

Test your policies against audit logs to ensure consistency:

permit test run audit

Options:

  • --pdp-url <string> - PDP URL to test against (default: http://localhost:7766)
  • --time-frame <number> - Hours of audit logs to fetch (6-72, default: 24)
  • --users <string[]> - Filter by specific users
  • --resources <string[]> - Filter by specific resources
  • --tenant <string> - Filter by tenant
  • --action <string> - Filter by action
  • --decision <allow|deny> - Filter by decision outcome
  • --max-logs <number> - Maximum logs to process

Examples:

# Basic test with last 24 hours
permit test run audit

# Test with custom filters
permit test run audit --time-frame 48 --action read --decision allow

# Test specific users and resources
permit test run audit --users john@example.com alice@example.com --resources document:123

# Limit processed logs
permit test run audit --max-logs 500

End-to-End Testing​

Generate test scenarios for your policies:

permit test generate e2e --models RBAC --path tests.json

Options:

  • --api-key <string> - API key for test generation
  • --dry-run <boolean> - Generate tests without applying changes
  • --models <string[]> - Policy models to test (default: RBAC)
  • --path <string> - Path to save test configuration

Examples:

# Generate RBAC tests and save config
permit test generate e2e --models RBAC --path tests.json

# Dry run - generate without applying
permit test generate e2e --models RBAC --path tests.json --dry-run

# Generate multiple model tests
permit test generate e2e --models RBAC ABAC --dry-run

Local PDP Management​

Run and interact with local Policy Decision Points for development, testing, and production deployment.

Run Local PDP​

Start a local Policy Decision Point for development and testing:

permit pdp run

This starts a local PDP instance on port 7766.

Check Permissions​

Test authorization decisions against your local PDP:

permit pdp check \
  --user "john@example.com" \
  --action "read" \
  --resource "document"

URL-based Permissions​

Check URL-based permissions using the PDP:

permit pdp check-url \
  --user "john@example.com" \
  --url "https://api.example.com/orders" \
  --method "GET"

Options:

  • --user <string> - User ID (required)
  • --url <string> - URL to check (required)
  • --method <string> - HTTP method (default: GET)
  • --tenant <string> - Tenant context (default: default)
  • --user-attributes <string> - Additional user attributes (key1:value1,key2:value2)
  • --pdp-url <string> - PDP URL (default: Cloud PDP)

PDP Statistics​

View performance metrics and audit statistics from your PDP instances:

permit pdp stats

GitOps Integration​

Manage authorization policies as code with GitOps workflows and version control.

Configure GitHub GitOps​

Set up GitOps workflow with GitHub:

permit gitops create github --inactive false

Options:

  • --inactive <boolean> - Set environment inactive after GitOps setup (default: false)

Clone GitOps Environment​

Clone environment or project from GitOps repository:

permit gitops env clone

Options:

  • --api-key <string> - API key for project selection
  • --dry-run - Display commands without execution
  • --project - Clone entire project instead of environment

OpenAPI Integration​

Generate authorization policies directly from OpenAPI specifications using Permit extensions.

Apply OpenAPI Specification​

Create policies from OpenAPI specifications with -x-permit extensions:

permit env apply openapi --spec-file ./api-spec.json

Options:

  • --api-key <string> - API key for authentication
  • --spec-file <string> - Path to OpenAPI file (local or HTTP)

Example OpenAPI 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
  /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

Policy Templates​

Use predefined policy templates to quickly set up common authorization fine-grained policies.

List Available Templates​

View all available policy templates:

permit env template list

Apply Policy Template​

Apply a predefined template to your environment:

permit env template apply --template mesa-verde-banking-demo

Options:

  • --api-key <string> - API key for template application
  • --local - Run Terraform locally (requires Terraform installation)
  • --template <string> - Specific template to apply

Proxy Management​

Configure API proxies for URL-based authorization and request routing.

Create Proxy Configuration​

Set up API proxy configurations for URL-based authorization:

permit api create proxy \
  --key "stripe-api" \
  --name "Stripe API Proxy" \
  --secret "your-secret" \
  --auth-mechanism "Bearer" \
  --mapping-rules "get|https://api.stripe.com/v1/customers|customers|list"

Options:

  • --api-key <string> - Your Permit API key
  • --secret <string> - Proxy secret for backend authentication
  • --key <string> - Unique proxy identifier
  • --name <string> - Human-readable proxy name
  • --auth-mechanism <string> - Authentication method (Bearer, Basic, Headers)
  • --mapping-rules - URL mapping rules in format: method|url|resource|action|priority|headers|url_type

List Proxy Configurations​

View all proxy configurations in your environment:

permit api list proxy

Options:

  • --api-key <string> - Your Permit API key
  • --expand-key - Show full key values
  • --page <number> - Page number (default: 1)
  • --per-page <number> - Items per page (default: 30)
  • --all - Fetch all pages

OPA Integration​

Integrate with Open Policy Agent (OPA) for advanced policy management and evaluation.

View OPA Policies​

Display policies from an OPA instance:

permit opa policy --server-url http://localhost:8181

Options:

  • --server-url <string> - OPA server URL (default: http://localhost:8181)
  • --api-key <string> - API key for authentication

Environment Management​

Create, manage, and configure environments for different stages of your application lifecycle.

Create Environment​

Create a new environment for your project:

permit env create --name "Staging" --description "Staging environment for testing"

Options:

  • --api-key <string> - Permit API key
  • --name <string> - Environment name
  • --description <string> - Environment description
  • --env-key <string> - Environment key
  • --custom-branch-name <string> - Custom branch name for GitOps
  • --jwks <string> - JWKS configuration
  • --settings <string> - Environment settings

Copy Environment​

Copy policies between environments:

permit env copy --source-env "production" --target-env "staging"

Delete Environment​

Delete an environment:

permit env delete --env-key "staging"

Environment Members​

Add members to an environment and assign roles:

permit env member --email "user@example.com" --role "admin"

Select Environment​

Switch active environment context:

permit env select

This command lets you select a different active environment without logging out and logging in again.

Options:

  • --api-key <string> - API key at project level or higher for authentication

Export Environment as Terraform​

Export your Permit environment configuration as a Terraform HCL file:

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

This exports all environment content (resources, roles, user sets, resource sets, condition sets) in the Permit Terraform provider format.

Options:

  • --api-key <string> - Permit API key for authentication
  • --file <string> - File path where the exported HCL should be saved (prints to console if not provided)

Advanced Usage​

Explore advanced CLI features for complex authorization scenarios and bulk operations.

Bulk Operations​

The CLI supports bulk operations for data management:

# Bulk user operations
permit api users list --all --role admin

# Bulk testing
permit test run audit --max-logs 1000

Custom Attributes​

Use attributes for advanced ABAC policies:

permit api sync user \
  --key "alice@example.com" \
  --attributes "department:engineering" \
  --attributes "level:senior" \
  --attributes "location:remote" \
  --roles "developer"

Multi-tenant Support​

Manage users across multiple tenants:

# Assign user to multiple tenants
permit api sync user \
  --key "bob@example.com" \
  --roles "admin:tenant-a" \
  --roles "viewer:tenant-b" \
  --roles "editor:tenant-c"

Configuration​

Authentication​

You can authenticate with your Permit.io account in several ways:

  1. Command line argument: 
    permit api users list --api-key permit_key_abc123
  2. Login session: 
    permit login
    permit api users list

Project and Environment Context​

Commands automatically use your current project and environment context. You can override this if you're using project or workspace level API keys.

permit api users list \
  --project-id proj_abc123 \
  --env-id env_def456

Summary​

You now have access to a command-line interface for managing authorization policies. The CLI provides tools for policy creation, user management, testing, and deployment that integrate with your existing development workflows.

Key capabilities covered:

  • Policy creation using AI and simple templates
  • User synchronization and role management across tenants
  • Policy testing through audit replay and end-to-end scenarios
  • Local PDP deployment for development and testing
  • GitOps integration and OpenAPI specification support
  • Proxy configuration for URL-based authorization

The CLI enables you to automate authorization workflows and maintain consistent policies across environments.

For additional resources, see the complete Readme file in the Permit CLI GitHub repository or join the CLI Slack community for support.

Contents