@permify-toolkit/cli

The Permify Toolkit CLI provides a set of commands to manage your Permify configuration and schema efficiently. It simplifies the process of interacting with your Permify instance directly from your terminal.

Installation

This package is intended to be used with pnpm.

pnpm add -D @permify-toolkit/cli

Configuration

The CLI relies on a permify.config.ts file in your project root. This file defines your Permify client connection settings and your schema structure.

Schema Definition Options

You can define your schema in two ways:

1. Inline Schema (AST-based)

Define your schema directly in the config file using the schema() function:

import {
  defineConfig,
  schema,
  entity,
  relation,
  permission
} from "@permify-toolkit/core";

export default defineConfig({
  tenant: "t1", // Optional: default tenant for CLI commands
  client: {
    endpoint: "localhost:3478",
    insecure: true // Use for local development without SSL
  },
  schema: schema({
    user: entity({
      relations: {
        manager: relation("user")
      },
      permissions: {
        manage: permission("manager")
      }
    }),
    document: entity({
      relations: {
        owner: relation("user"),
        viewer: relation("user")
      },
      permissions: {
        view: permission("viewer or owner"),
        edit: permission("owner")
      }
    })
  }),

  relationships: {
    seedFile: "./relationships.json",
    mode: "append" // "append" (default) or "replace"
  }
});

2. File-based Schema

Reference an external .perm schema file using the schemaFile() function:

import { defineConfig, schemaFile } from "@permify-toolkit/core";

export default defineConfig({
  tenant: "t1", // Optional: default tenant for CLI commands
  client: {
    endpoint: "localhost:3478",
    insecure: true
  },
  schema: schemaFile("./schema.perm")
});

Example schema.perm file:

entity user {}

entity organization {
  relation member @user

  permission view = member
}

entity document {
  relation owner @user
  relation parent @organization

  permission view = owner or parent.view
  permission edit = owner
}

Client Configuration Options

Tenant Configuration

The --tenant flag is optional if you define tenant in your permify.config.ts.

Resolution order:

1. --tenant CLI flag (or PERMIFY_TENANT env var)
2. tenant field in permify.config.ts
3. Error if neither is provided

This means you can set your tenant once in the config and skip the flag entirely:

# No --tenant needed if tenant is in permify.config.ts
permify-toolkit schema push
permify-toolkit relationships seed --file-path ./data/relationships.json

Commands

schema push

Pushes the schema defined in your permify.config.ts to the configured Permify server.

Usage:

permify-toolkit schema push [--tenant <tenant-id>] [flags]

Flags:

Examples:

Push using tenant from config:

permify-toolkit schema push

Push to a specific tenant (overrides config):

permify-toolkit schema push --tenant my-tenant-id

Push to a tenant, creating it if it doesn't exist:

permify-toolkit schema push --tenant new-tenant-id --create-tenant

Schema Validation:

The Permify server validates your schema when you push it. If there are any errors (e.g., referencing non-existent entities), you'll receive a detailed error message:

Error: Entity "usr" referenced in relation "document.owner" does not exist

relationships seed

Seeds relationship data from a JSON file to the configured Permify server.

Usage:

permify-toolkit relationships seed --tenant <tenant-id> --file-path <path-to-file> [flags]

Flags:

Example relationships.json file:

The JSON file must contain a tuples array, where each tuple object has entity, relation, and subject fields.

{
  "tuples": [
    {
      "entity": {
        "type": "organization",
        "id": "org_1"
      },
      "relation": "member",
      "subject": {
        "type": "user",
        "id": "alice"
      }
    },
    {
      "entity": {
        "type": "document",
        "id": "doc_1"
      },
      "relation": "owner",
      "subject": {
        "type": "user",
        "id": "bob"
      }
    },
    {
      "entity": {
        "type": "document",
        "id": "doc_1"
      },
      "relation": "viewer",
      "subject": {
        "type": "user",
        "id": "charlie"
      }
    }
  ]
}

Examples:

Seed relationships to an existing tenant:

permify-toolkit relationships seed --tenant my-tenant-id --file-path ./data/relationships.json

Seed relationships to a new tenant:

permify-toolkit relationships seed --tenant new-tenant-id --file-path ./relationships.json --create-tenant

Development

To develop and test changes locally:

1. Make your changes.
2. Build the package:

   pnpm build

3. Run the CLI using the local bin script:

   ./bin/permify-toolkit <command> [flags]

Example:

./bin/permify-toolkit schema push --tenant dev-tenant -c

Features

• Flexible Schema Definition: Choose between inline TypeScript schemas or external .perm files
• Type Safety: Full TypeScript support with autocomplete for inline schemas
• Schema Validation: Permify validates your schema on push, catching errors early
• Tenant Management: Automatically create tenants if they don't exist
• Secure & Insecure Connections: Support for both SSL/TLS and insecure local development
• File Validation: Automatic validation of .perm file paths and extensions