Skip to main content

Use the Permit CLI

Now that you've learned how to configure policies and perform authorization checks, let's explore how to manage your authorization system programmatically using the Permit CLI. The CLI provides powerful tools for policy management, testing, and automation that complement the web interface and SDKs you've already learned about.

CLI Capabilities & Reference​

The Permit CLI is an open-source command-line tool that empowers developers to manage, test, and automate fine-grained access control across applications. It provides a comprehensive interface to all of Permit's functionality, including AI-powered policy generation, interactive wizards, policy testing, and local PDP management.

For the complete CLI specification and all available commands, explore the Permit CLI repository and its full documentation.

Prerequisites​

Before starting this walkthrough, ensure you have:

1

Install and authenticate with the CLI​

The Permit CLI is available as an npm package and provides a command-line interface to all of Permit's functionality.

  1. Install the CLI globally:

    npm install -g @permitio/cli

  2. Verify the installation:

    permit

    You should see the following output:

    Permit CLI is a developer swiss army knife for fine-grained authorization
    Run this command with --help for more information

    You're not logged in. Run `permit login` to activate all CLI features.

  3. Authenticate with your Permit account:

    permit login

    This will open your browser to authenticate with Permit.io. After successful authentication, your credentials will be stored locally.

  4. Verify your authentication:

    permit

    You should see your account information displayed.

  5. Create an environment:

    permit env create

    Now, you can create a new environment so you can start creating policies.

2

Create policies using AI​

The CLI includes AI-powered policy generation that can create structured RBAC policies from natural language descriptions. This is perfect for quickly prototyping authorization models.

  1. Start the AI policy creation:

    permit policy create ai

  2. Describe your authorization requirements:

    When prompted, describe your application's authorization needs. For example:

    A document management system with three user types: admins who can do everything, editors who can create and edit documents, and viewers who can only read documents.

  3. Review and approve the generated policy:

    The AI will generate a structured policy with resources, roles, and permissions. Review the output and approve it to apply the policy to your environment.

tip

The AI policy generator is particularly useful for rapid prototyping and can help you discover authorization patterns you might not have considered.

3

Use interactive policy wizards​

For more control over policy creation, use the interactive wizard that guides you through each step.

  1. Initialize the policy wizard:

    permit init

    This will guide you through creating a complete authorization policy step by step, similar to what you did in the web interface.

  2. Or use the simple policy creator for quick setup:

    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"

    This creates a document management system with three roles and their respective permissions, similar to the RBAC policy you configured earlier.

4

Sync users and assign roles​

Now let's add users and assign them roles using the CLI, building on what you learned about user syncing.

  1. Sync a user with role assignment:

    permit api sync user \
      --key "john@example.com" \
      --email "john@example.com" \
      --first_name "John" \
      --last_name "Doe" \
      --roles "admin"

  2. Sync another user with a different role:

    permit api sync user \
      --key "jane@example.com" \
      --email "jane@example.com" \
      --first_name "Jane" \
      --last_name "Smith" \
      --roles "editor"

  3. Verify user assignments:

    permit api users list

    This shows all users in your environment, similar to the Directory view in the web interface.

5

Perform policy checks from the command line​

Now let's test your authorization policies using the CLI, building on your understanding of policy checks.

  1. Run a local PDP:

    permit pdp run

    This will start a local PDP instance on port 7766.

  2. Check if John can create a document:

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

    You should see output indicating whether the user is permitted or denied.

  3. Check if Jane can delete a document:

    permit pdp check \
      --user "jane@example.com" \
      --action "delete" \
      --resource "document"

  4. Check if Jane can read a document:

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

    These checks work the same way as the permit.check() function you learned about, but from the command line.

What did you learn?​

In this walkthrough, you've successfully:

  • ✅ Installed and authenticated with the Permit CLI
  • ✅ Created authorization policies using AI and interactive wizards
  • ✅ Synced users and assigned appropriate roles from the command line
  • ✅ Performed policy checks to verify your authorization rules
  • ✅ Tested your policies with audit replay and end-to-end tests
  • ✅ Run a local PDP for development and testing

The CLI complements the web interface and SDKs you've already learned about, providing a powerful command-line workflow for policy management and automation.

FUN FACT!

Command-line interfaces have been around since the 1960s! The first CLI was developed for the Compatible Time-Sharing System (CTSS) at MIT, and they've remained essential tools for developers ever since.

What's next? 🎉

  • Set up a local authorization microservice for production deployment
  • Configure attribute-based access control (ABAC) policies
  • Learn about relationship-based access control (ReBAC)
  • Explore advanced authorization queries and data filtering

Excellent! You've mastered the CLI workflow.

Contents