From 5375f7ab32e2f08ab028c9121ef507ff2311cf8b Mon Sep 17 00:00:00 2001 From: Gabriel Manor Date: Wed, 18 Jun 2025 12:25:43 +0300 Subject: [PATCH 1/4] Initial Docs --- .../access-requests-and-approvals.mdx | 5 +- .../advanced-authorization-queries.mdx | 5 +- docs/overview/create-a-rebac-policy.mdx | 5 +- .../local-authorization-microservice.mdx | 7 +- .../perform-policy-check-with-cloud-pdp.mdx | 3 +- docs/overview/permit-cli-quickstart.mdx | 247 ++++++++ .../setup-attribute-based-access-control.mdx | 7 +- docs/overview/sync-applications-data.mdx | 7 +- .../sync-your-first-user-with-sdk.mdx | 2 +- docs/sdk/permit-cli-reference.mdx | 593 ++++++++++++++++++ sidebars.js | 7 +- 11 files changed, 870 insertions(+), 18 deletions(-) create mode 100644 docs/overview/permit-cli-quickstart.mdx create mode 100644 docs/sdk/permit-cli-reference.mdx diff --git a/docs/overview/access-requests-and-approvals.mdx b/docs/overview/access-requests-and-approvals.mdx index ee04cfd8..626c3e76 100644 --- a/docs/overview/access-requests-and-approvals.mdx +++ b/docs/overview/access-requests-and-approvals.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 9 -title: Access Requests & Approvals +sidebar_position: 11 +title: Access Requests and Approvals +description: Learn how to implement access request workflows and approval processes. --- In this tutorial, you will learn how to integrate an access request and approval system into your app using Permit.io. We'll diff --git a/docs/overview/advanced-authorization-queries.mdx b/docs/overview/advanced-authorization-queries.mdx index befe6982..cc18d253 100644 --- a/docs/overview/advanced-authorization-queries.mdx +++ b/docs/overview/advanced-authorization-queries.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 8 +sidebar_position: 10 title: Advanced Authorization Queries +description: Learn advanced techniques for querying and filtering authorization data. --- Authorization plays a crucial role in managing secure access to your systems, and advanced queries can make this process more @@ -118,7 +119,7 @@ permission. Today, we use advanced databases and APIs, but the goal remains the the right things. ::: - +

What's next? πŸŽ‰

  • Implement bulk permission checks to optimize authorization workflows
    • diff --git a/docs/overview/create-a-rebac-policy.mdx b/docs/overview/create-a-rebac-policy.mdx index 21111768..53d2d813 100644 --- a/docs/overview/create-a-rebac-policy.mdx +++ b/docs/overview/create-a-rebac-policy.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 6 +sidebar_position: 8 title: Create a ReBAC Policy +description: Learn how to create relationship-based access control policies. --- import WhatsNext from "../../src/components/whats-next/WhatsNext"; @@ -369,7 +370,7 @@ Now, let's use the provided snippet with out PDP to validate if the user can per - +

    What's next? πŸŽ‰

    • Assign roles and permissions to users and tenants
      • diff --git a/docs/overview/local-authorization-microservice.mdx b/docs/overview/local-authorization-microservice.mdx index bbfb3e5e..150ef4ef 100644 --- a/docs/overview/local-authorization-microservice.mdx +++ b/docs/overview/local-authorization-microservice.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 4 -title: Run Local Authorization Microservice +sidebar_position: 6 +title: Local Authorization Microservice +description: Set up and run a local Policy Decision Point (PDP) for enhanced performance and security. timeline: true --- @@ -202,7 +203,7 @@ From this walkthrough, you've learned: A well-configured local PDP can handle **thousands** of authorization decisions per second with **sub-millisecond latency**, making it perfect for high-performance applications. Some of our customers process **millions** of decisions daily with a single PDP instance! ::: - +

      What's next? πŸŽ‰

      • Create user and resource attributes
        • diff --git a/docs/overview/perform-policy-check-with-cloud-pdp.mdx b/docs/overview/perform-policy-check-with-cloud-pdp.mdx index d24fe4cd..4e75f9fc 100644 --- a/docs/overview/perform-policy-check-with-cloud-pdp.mdx +++ b/docs/overview/perform-policy-check-with-cloud-pdp.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 title: Run your First Policy Check timeline: true --- @@ -149,6 +149,7 @@ Companies like Netflix use similar mechanisms to authorize every single request

        What's next? πŸŽ‰

          +
        • Manage policies with the Permit CLI for command-line workflows
        • Set up a local PDP for enhanced performance
        • Configure your application for local authorization
        • Learn about monitoring and debugging your PDP
          • diff --git a/docs/overview/permit-cli-quickstart.mdx b/docs/overview/permit-cli-quickstart.mdx new file mode 100644 index 00000000..013948d4 --- /dev/null +++ b/docs/overview/permit-cli-quickstart.mdx @@ -0,0 +1,247 @@ +--- +sidebar_position: 5 +title: Use the Permit CLI +description: Use the Permit CLI to manage, test, and automate your authorization policies from the command line. +--- + +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. + +import TimelineStep from "../../src/components/timeline/TimelineStep"; +import TimelineWrapper from "../../src/components/timeline/TimelineWrapper"; +import WhatsNext from "../../src/components/whats-next/WhatsNext"; + + +## 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](https://github.com/permitio/permit-cli) and its [full documentation](https://github.com/permitio/permit-cli#full-command-list). + +## Prerequisites + +Before starting this walkthrough, ensure you have: + +- A [Permit.io account](https://app.permit.io) with an active project +- Node.js 16+ installed on your system +- Basic familiarity with command-line tools +- Completed the previous walkthroughs: [Configure your first RBAC policy](/overview/configure-your-first-rbac-policy), [Use the Permit API and SDK](/overview/use-the-permit-api-and-sdk), [Sync your first user](/overview/sync-your-first-user-with-sdk), and [Perform policy checks](/overview/perform-policy-check-with-cloud-pdp) + + + + +## 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:** + + ```bash + npm install -g @permitio/cli + ``` + +2. **Verify the installation:** + + ```bash + 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:** + + ```bash + 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:** + + ```bash + permit + ``` + + You should see your account information displayed. + +5. **Create an environment:** + + ```bash + permit env create + ``` + + Now, you can create a new environment so you can start creating policies. + + + + +## 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:** + + ```bash + 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. +::: + + + + +## 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:** + + ```bash + 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:** + + ```bash + 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. + + + + +## 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:** + + ```bash + 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:** + + ```bash + permit api sync user \ + --key "jane@example.com" \ + --email "jane@example.com" \ + --first_name "Jane" \ + --last_name "Smith" \ + --roles "editor" + ``` + +3. **Verify user assignments:** + + ```bash + permit api users list + ``` + + This shows all users in your environment, similar to the Directory view in the web interface. + + + + +## 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:** + + ```bash + permit pdp run + ``` + + This will start a local PDP instance on port 7766. + +2. **Check if John can create a document:** + + ```bash + 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:** + + ```bash + permit pdp check \ + --user "jane@example.com" \ + --action "delete" \ + --resource "document" + ``` + +4. **Check if Jane can read a document:** + + ```bash + 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. + +:::tip 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
            • +
          +           \ No newline at end of file diff --git a/docs/overview/setup-attribute-based-access-control.mdx b/docs/overview/setup-attribute-based-access-control.mdx index a9779533..2991dd43 100644 --- a/docs/overview/setup-attribute-based-access-control.mdx +++ b/docs/overview/setup-attribute-based-access-control.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 4 -title: Create an ABAC Policy +sidebar_position: 7 +title: Setup Attribute-Based Access Control +description: Learn how to create and configure ABAC policies using user and resource attributes. --- Attribute-Based Access Control (ABAC) is a powerful and flexible access control method that uses @@ -141,7 +142,7 @@ resourcesβ€”if the conditions (like their role, location, and task type) align p policy. This adaptability makes ABAC a popular choice for modern, cloud-based systems ::: - +

          What's next? πŸŽ‰

          • Define resource relations and parent-child structures
            • diff --git a/docs/overview/sync-applications-data.mdx b/docs/overview/sync-applications-data.mdx index 64895bfb..7c110317 100644 --- a/docs/overview/sync-applications-data.mdx +++ b/docs/overview/sync-applications-data.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 7 -title: Sync Data into your App +sidebar_position: 9 +title: Sync Applications Data +description: Learn how to sync application data into Permit for advanced authorization scenarios. --- import userAttributes from "../../static/ui-videos/walkthroughs/sync-data/user-attribute.mp4"; @@ -235,7 +236,7 @@ Did you know that the concept of data synchronization dates back to the early da In the 19th century, synchronization was first used to align clocks for railway systems to prevent train collisions. ::: - +

            What's next? πŸŽ‰

            • Implement bulk permission checks to optimize authorization workflows
              • diff --git a/docs/overview/sync-your-first-user-with-sdk.mdx b/docs/overview/sync-your-first-user-with-sdk.mdx index 06034758..97fbaa65 100644 --- a/docs/overview/sync-your-first-user-with-sdk.mdx +++ b/docs/overview/sync-your-first-user-with-sdk.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 title: Sync your First User --- diff --git a/docs/sdk/permit-cli-reference.mdx b/docs/sdk/permit-cli-reference.mdx new file mode 100644 index 00000000..e9d858d9 --- /dev/null +++ b/docs/sdk/permit-cli-reference.mdx @@ -0,0 +1,593 @@ +--- +sidebar_position: 1 +title: Permit CLI Reference +description: Complete command-line interface for managing Permit.io authorization policies, testing, and automation. +--- + +The **Permit CLI** is a powerful command-line tool that provides comprehensive access to all of 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. + +import WhatsNext from "../../src/components/whats-next/WhatsNext"; + +--- + +## Installation + +Install the Permit CLI globally using npm: + +```bash +npm install -g @permitio/cli +``` + +Verify the installation: + +```bash +permit +``` + +--- + +## Authentication + +Before using the CLI, you need to authenticate with your Permit.io account: + +```bash +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: + +```bash +permit logout +``` + +--- + +## Core Commands + +### Policy Management + +#### Create Policies with AI + +Generate RBAC policies using natural language descriptions: + +```bash +permit policy create ai +``` + +The AI will guide you through describing your authorization requirements and generate structured policies with resources, roles, and permissions. + +**Example:** +```bash +$ 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: + +```bash +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 ` - Permit API key for the environment +- `--resources ` - Array of resources in format: `key:name@attribute1,attribute2` +- `--actions ` - Array of actions in format: `key:description` +- `--roles ` - Array of roles in format: `role|resource:action|resource:action` + +### User Management + +#### Sync Users + +Create or update users in your Permit environment: + +```bash +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 ` - Unique user identifier (required) +- `--email ` - User email address +- `--first_name ` - User's first name +- `--last_name ` - User's last name +- `--attributes ` - 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 ` - Permit API key (optional) + +#### List Users + +Retrieve all users in your environment: + +```bash +permit api users list +``` + +**Options:** +- `--api-key ` - Your Permit API key +- `--project-id ` - Project ID +- `--env-id ` - Environment ID +- `--role ` - Filter by role +- `--tenant ` - Filter by tenant +- `--all` - Fetch all pages +- `--page ` - Page number (default: 1) +- `--per-page ` - Items per page (default: 50) + +#### Assign/Unassign Roles + +Manage user role assignments: + +```bash +# 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 + +#### Audit Log Replay + +Test your policies against audit logs to ensure consistency: + +```bash +permit test run audit +``` + +**Options:** +- `--pdp-url ` - PDP URL to test against (default: `http://localhost:7766`) +- `--time-frame ` - Hours of audit logs to fetch (6-72, default: 24) +- `--users ` - Filter by specific users +- `--resources ` - Filter by specific resources +- `--tenant ` - Filter by tenant +- `--action ` - Filter by action +- `--decision ` - Filter by decision outcome +- `--max-logs ` - Maximum logs to process + +**Examples:** +```bash +# 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 comprehensive test scenarios for your policies: + +```bash +permit test generate e2e --models RBAC --path tests.json +``` + +**Options:** +- `--api-key ` - API key for test generation +- `--dry-run ` - Generate tests without applying changes +- `--models ` - Policy models to test (default: RBAC) +- `--path ` - Path to save test configuration + +**Examples:** +```bash +# 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 Local PDP + +Start a local Policy Decision Point for development and testing: + +```bash +permit pdp run +``` + +This starts a local PDP instance on port 7766. + +#### Check Permissions + +Test authorization decisions against your local PDP: + +```bash +permit pdp check \ + --user "john@example.com" \ + --action "read" \ + --resource "document" +``` + +#### URL-based Permissions + +Check URL-based permissions using the PDP: + +```bash +permit pdp check-url \ + --user "john@example.com" \ + --url "https://api.example.com/orders" \ + --method "GET" +``` + +**Options:** +- `--user ` - User ID (required) +- `--url ` - URL to check (required) +- `--method ` - HTTP method (default: GET) +- `--tenant ` - Tenant context (default: default) +- `--user-attributes ` - Additional user attributes (key1:value1,key2:value2) +- `--pdp-url ` - PDP URL (default: Cloud PDP) + +#### PDP Statistics + +View performance metrics and audit statistics from your PDP instance: + +```bash +permit pdp stats +``` + +### GitOps Integration + +#### Configure GitHub GitOps + +Set up GitOps workflow with GitHub: + +```bash +permit gitops create github --inactive false +``` + +**Options:** +- `--inactive ` - Set environment inactive after GitOps setup (default: false) + +#### Clone GitOps Environment + +Clone environment or project from GitOps repository: + +```bash +permit gitops env clone +``` + +**Options:** +- `--api-key ` - API key for project selection +- `--dry-run` - Display commands without execution +- `--project` - Clone entire project instead of environment + +### OpenAPI Integration + +#### Apply OpenAPI Specification + +Create policies from OpenAPI specifications with `-x-permit` extensions: + +```bash +permit env apply openapi --spec-file ./api-spec.json +``` + +**Options:** +- `--api-key ` - API key for authentication +- `--spec-file ` - Path to OpenAPI file (local or HTTP) + +**Example OpenAPI with Permit Extensions:** +```yaml +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 +``` + +### Template Management + +#### List Available Templates + +View all available policy templates: + +```bash +permit env template list +``` + +#### Apply Policy Template + +Apply a predefined template to your environment: + +```bash +permit env template apply --template mesa-verde-banking-demo +``` + +**Options:** +- `--api-key ` - API key for template application +- `--local` - Run Terraform locally (requires Terraform installation) +- `--template ` - Specific template to apply + +### Proxy Management + +#### Create Proxy Configuration + +Set up API proxy configurations for URL-based authorization: + +```bash +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 ` - Your Permit API key +- `--secret ` - Proxy secret for backend authentication +- `--key ` - Unique proxy identifier +- `--name ` - Human-readable proxy name +- `--auth-mechanism ` - 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: + +```bash +permit api list proxy +``` + +**Options:** +- `--api-key ` - Your Permit API key +- `--expand-key` - Show full key values +- `--page ` - Page number (default: 1) +- `--per-page ` - Items per page (default: 30) +- `--all` - Fetch all pages + +### OPA Integration + +#### View OPA Policies + +Display policies from an OPA instance: + +```bash +permit opa policy --server-url http://localhost:8181 +``` + +**Options:** +- `--server-url ` - OPA server URL (default: http://localhost:8181) +- `--api-key ` - API key for authentication + +--- + +## Environment Management + +### Create Environment + +Create a new environment for your project: + +```bash +permit env create --name "Staging" --description "Staging environment for testing" +``` + +**Options:** +- `--api-key ` - Permit API key +- `--name ` - Environment name +- `--description ` - Environment description +- `--env-key ` - Environment key +- `--custom-branch-name ` - Custom branch name for GitOps +- `--jwks ` - JWKS configuration +- `--settings ` - Environment settings + +### Copy Environment + +Copy policies between environments: + +```bash +permit env copy --source-env "production" --target-env "staging" +``` + +### Delete Environment + +Delete an environment: + +```bash +permit env delete --env-key "staging" +``` + +### Environment Members + +Add members to an environment and assign roles: + +```bash +permit env member --email "user@example.com" --role "admin" +``` + +--- + +## Advanced Usage + +### Bulk Operations + +The CLI supports bulk operations for efficient data management: + +```bash +# 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: + +```bash +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: + +```bash +# 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 + +### API Key Management + +You can provide API keys in several ways: + +1. **Command line argument:** + ```bash + permit api users list --api-key permit_key_abc123 + ``` + +2. **Environment variable:** + ```bash + export PERMIT_API_KEY=permit_key_abc123 + permit api users list + ``` + +3. **Login session:** + ```bash + permit login + permit api users list + ``` + +### Project and Environment Context + +Most commands automatically use your current project and environment context. You can override this: + +```bash +permit api users list \ + --project-id proj_abc123 \ + --env-id env_def456 +``` + +--- + +## Troubleshooting + +### Common Issues + +**Authentication Errors:** +```bash +# Re-authenticate +permit login + +# Log out and clear credentials +permit logout +``` + +**Permission Denied:** +- Ensure your API key has the necessary permissions +- Check that you're in the correct project and environment + +**Connection Issues:** +- Verify your internet connection +- Check if Permit.io services are available +- Try using a different API key + +### Debug Mode + +Enable debug logging for troubleshooting: + +```bash +# Set debug environment variable +export DEBUG=permit-cli:* + +# Run commands with debug output +permit api users list +``` + +--- + +## What did you learn? + +In this comprehensive CLI reference, you've learned how to: + +- **Install and authenticate** with the Permit CLI +- **Create and manage policies** using AI and simple commands +- **Sync and manage users** with role assignments across tenants +- **Test policies** using audit replay and end-to-end testing +- **Run local PDPs** for development and testing +- **Integrate with GitOps** workflows and OpenAPI specifications +- **Manage proxy configurations** for URL-based authorization +- **Use advanced features** like bulk operations and custom attributes + +The CLI provides a complete command-line interface to all of Permit.io's functionality, enabling automation, testing, and efficient policy management. + +:::tip FUN FACT! +The Permit CLI is built using Pastel, a React-like library for building CLI applications. This allows for rich, interactive command-line experiences with components and state management, making complex authorization workflows feel intuitive and user-friendly. +::: + + +

              What's next? πŸŽ‰

              + +               diff --git a/sidebars.js b/sidebars.js index fe510f60..523bb2aa 100644 --- a/sidebars.js +++ b/sidebars.js @@ -88,9 +88,9 @@ const sidebars = { "overview/use-the-permit-api-and-sdk", "overview/sync-your-first-user-with-sdk", "overview/perform-policy-check-with-cloud-pdp", + "overview/permit-cli-quickstart", "overview/local-authorization-microservice", "overview/setup-attribute-based-access-control", - // "overview/perform-a-local-policy-check", "overview/create-a-rebac-policy", "overview/sync-applications-data", "overview/advanced-authorization-queries", @@ -398,6 +398,11 @@ const sidebars = { collapsible: false, className: "category-as-header", items: [ + { + type: "doc", + id: "sdk/permit-cli-reference", + label: "Permit CLI", + }, { type: "category", label: "NodeJS", From 7a4fabdf6535095bb29307af8b4bbadd3d45ff6a Mon Sep 17 00:00:00 2001 From: Gabriel Manor Date: Wed, 18 Jun 2025 14:30:50 +0300 Subject: [PATCH 2/4] Alignment --- docs/sdk/permit-cli-reference.mdx | 110 +++++++++++------------------- 1 file changed, 39 insertions(+), 71 deletions(-) diff --git a/docs/sdk/permit-cli-reference.mdx b/docs/sdk/permit-cli-reference.mdx index e9d858d9..bbab1cb0 100644 --- a/docs/sdk/permit-cli-reference.mdx +++ b/docs/sdk/permit-cli-reference.mdx @@ -1,14 +1,11 @@ --- sidebar_position: 1 title: Permit CLI Reference -description: Complete command-line interface for managing Permit.io authorization policies, testing, and automation. +description: Command-line interface for managing Permit.io authorization policies, testing, and automation. --- -The **Permit CLI** is a powerful command-line tool that provides comprehensive access to all of 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. +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. -import WhatsNext from "../../src/components/whats-next/WhatsNext"; - ---- ## Installation @@ -24,7 +21,6 @@ Verify the installation: permit ``` ---- ## Authentication @@ -42,12 +38,13 @@ 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: @@ -86,6 +83,8 @@ permit policy create simple \ ### User Management +Manage users, their attributes, and role assignments across your authorization system. + #### Sync Users Create or update users in your Permit environment: @@ -146,6 +145,8 @@ permit api users unassign --user "john@example.com" --role "admin" --tenant "def ### Policy Testing +Validate your authorization policies through testing and audit verification. + #### Audit Log Replay Test your policies against audit logs to ensure consistency: @@ -181,7 +182,7 @@ permit test run audit --max-logs 500 #### End-to-End Testing -Generate comprehensive test scenarios for your policies: +Generate test scenarios for your policies: ```bash permit test generate e2e --models RBAC --path tests.json @@ -207,6 +208,8 @@ 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: @@ -249,7 +252,7 @@ permit pdp check-url \ #### PDP Statistics -View performance metrics and audit statistics from your PDP instance: +View performance metrics and audit statistics from your PDP instances: ```bash permit pdp stats @@ -257,6 +260,8 @@ 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: @@ -283,6 +288,8 @@ permit gitops env clone ### OpenAPI Integration +Generate authorization policies directly from OpenAPI specifications using Permit extensions. + #### Apply OpenAPI Specification Create policies from OpenAPI specifications with `-x-permit` extensions: @@ -328,7 +335,9 @@ paths: x-permit-role: admin ``` -### Template Management +### Policy Templates + +Use predefined policy templates to quickly set up common authorization fine-grained policies. #### List Available Templates @@ -353,6 +362,8 @@ permit env template apply --template mesa-verde-banking-demo ### Proxy Management +Configure API proxies for URL-based authorization and request routing. + #### Create Proxy Configuration Set up API proxy configurations for URL-based authorization: @@ -391,6 +402,8 @@ permit api list proxy ### OPA Integration +Integrate with Open Policy Agent (OPA) for advanced policy management and evaluation. + #### View OPA Policies Display policies from an OPA instance: @@ -407,6 +420,8 @@ permit opa policy --server-url http://localhost:8181 ## Environment Management +Create, manage, and configure environments for different stages of your application lifecycle. + ### Create Environment Create a new environment for your project: @@ -452,9 +467,11 @@ permit env member --email "user@example.com" --role "admin" ## Advanced Usage +Explore advanced CLI features for complex authorization scenarios and bulk operations. + ### Bulk Operations -The CLI supports bulk operations for efficient data management: +The CLI supports bulk operations for data management: ```bash # Bulk user operations @@ -525,69 +542,20 @@ permit api users list \ --env-id env_def456 ``` ---- - -## Troubleshooting - -### Common Issues - -**Authentication Errors:** -```bash -# Re-authenticate -permit login -# Log out and clear credentials -permit logout -``` +## Summary -**Permission Denied:** -- Ensure your API key has the necessary permissions -- Check that you're in the correct project and environment +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. -**Connection Issues:** -- Verify your internet connection -- Check if Permit.io services are available -- Try using a different API key +**Key capabilities covered:** -### Debug Mode +- 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 -Enable debug logging for troubleshooting: - -```bash -# Set debug environment variable -export DEBUG=permit-cli:* - -# Run commands with debug output -permit api users list -``` - ---- +The CLI enables you to automate authorization workflows and maintain consistent policies across environments. -## What did you learn? - -In this comprehensive CLI reference, you've learned how to: - -- **Install and authenticate** with the Permit CLI -- **Create and manage policies** using AI and simple commands -- **Sync and manage users** with role assignments across tenants -- **Test policies** using audit replay and end-to-end testing -- **Run local PDPs** for development and testing -- **Integrate with GitOps** workflows and OpenAPI specifications -- **Manage proxy configurations** for URL-based authorization -- **Use advanced features** like bulk operations and custom attributes - -The CLI provides a complete command-line interface to all of Permit.io's functionality, enabling automation, testing, and efficient policy management. - -:::tip FUN FACT! -The Permit CLI is built using Pastel, a React-like library for building CLI applications. This allows for rich, interactive command-line experiences with components and state management, making complex authorization workflows feel intuitive and user-friendly. -::: - - -

              What's next? πŸŽ‰

              - -               +For additional resources, see the complete [Readme](https://github.com/permitio/permit-cli/blob/main/README.md) file in the [Permit CLI GitHub repository](https://github.com/permitio/permit-cli) or join the [CLI Slack community](https://io.permit.io/cli-slack) for support. From f2555bfdce97df8ca144fcfe1096b645b3d22865 Mon Sep 17 00:00:00 2001 From: Gabriel Manor Date: Wed, 18 Jun 2025 14:48:48 +0300 Subject: [PATCH 3/4] CLI --- src/components/home-page/home-cards-links.js | 15 ++++++++++++--- src/components/walkthroughs/home-cards-links.js | 7 +++++++ 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/src/components/home-page/home-cards-links.js b/src/components/home-page/home-cards-links.js index 46bfa077..b3b0f73a 100644 --- a/src/components/home-page/home-cards-links.js +++ b/src/components/home-page/home-cards-links.js @@ -79,10 +79,19 @@ export const sdkRow = [ }, { type: "link", - href: "sdk/golang/quickstart-golang", - label: "Golang", - icon: " ", + href: "sdk/permit-cli-reference", + label: "Permit CLI", + svgIcon: , + description: "Command-line interface for policy management and automation", }, + { + type: "link", + href: "https://api.permit.io/scalar", + label: "API Reference", + svgIcon: , + description: "Complete API documentation and interactive explorer", + }, + { type: "link", href: "sdk/golang/quickstart-golang", label: "Golang", icon: " " }, { type: "link", href: "sdk/nodejs/quickstart-nodejs", label: "Node.js", icon: " " }, { type: "link", href: "sdk/python/quickstart_python_sync", label: "Python", icon: " " }, { type: "link", href: "sdk/ruby/quickstart-ruby", label: "Ruby", icon: " " }, diff --git a/src/components/walkthroughs/home-cards-links.js b/src/components/walkthroughs/home-cards-links.js index dbafeb23..18377cfa 100644 --- a/src/components/walkthroughs/home-cards-links.js +++ b/src/components/walkthroughs/home-cards-links.js @@ -31,6 +31,13 @@ export const firstRow = [ svgIcon: , description: "Validate your access control by testing your first policy decision.", }, + { + type: "link", + href: "/overview/permit-cli-quickstart", + label: "Use the Permit CLI", + svgIcon: , + description: "Learn how to use the command-line interface for policy management and automation.", + }, { type: "link", href: "/overview/local-authorization-microservice", From 04a4e18bb98d463627ef067736cc2a9dfe24bbdc Mon Sep 17 00:00:00 2001 From: Gabriel Manor Date: Wed, 18 Jun 2025 16:49:02 +0300 Subject: [PATCH 4/4] Add Missing Commands --- docs/sdk/permit-cli-reference.mdx | 55 ++++++++++++++++++++++++------- 1 file changed, 44 insertions(+), 11 deletions(-) diff --git a/docs/sdk/permit-cli-reference.mdx b/docs/sdk/permit-cli-reference.mdx index bbab1cb0..3f086f53 100644 --- a/docs/sdk/permit-cli-reference.mdx +++ b/docs/sdk/permit-cli-reference.mdx @@ -81,6 +81,19 @@ permit policy create simple \ - `--actions ` - Array of actions in format: `key:description` - `--roles ` - Array of roles in format: `role|resource:action|resource:action` +#### Interactive Policy Wizard + +Initialize the policy creation wizard for step-by-step policy setup: + +```bash +permit init +``` + +This command guides you through creating a complete authorization policy interactively, similar to the web interface workflow. + +**Options:** +- `--api-key ` - Use an environment API key to create and store the policy + ### User Management Manage users, their attributes, and role assignments across your authorization system. @@ -463,6 +476,33 @@ Add members to an environment and assign roles: permit env member --email "user@example.com" --role "admin" ``` +### Select Environment + +Switch active environment context: + +```bash +permit env select +``` + +This command lets you select a different active environment without logging out and logging in again. + +**Options:** +- `--api-key ` - API key at project level or higher for authentication + +### Export Environment as Terraform + +Export your Permit environment configuration as a Terraform HCL file: + +```bash +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 ` - Permit API key for authentication +- `--file ` - File path where the exported HCL should be saved (prints to console if not provided) + --- ## Advanced Usage @@ -511,22 +551,15 @@ permit api sync user \ ## Configuration -### API Key Management +### Authentication -You can provide API keys in several ways: +You can authenticate with your Permit.io account in several ways: 1. **Command line argument:** ```bash permit api users list --api-key permit_key_abc123 ``` - -2. **Environment variable:** - ```bash - export PERMIT_API_KEY=permit_key_abc123 - permit api users list - ``` - -3. **Login session:** +2. **Login session:** ```bash permit login permit api users list @@ -534,7 +567,7 @@ You can provide API keys in several ways: ### Project and Environment Context -Most commands automatically use your current project and environment context. You can override this: +Commands automatically use your current project and environment context. You can override this if you're using project or workspace level API keys. ```bash permit api users list \