permio

Permio is hosted authorization for your app: RBAC and fine-grained permission checks on hierarchical resources, for multi-tenant SaaS.

Website · Docs · Quickstart · Dashboard

permio is the command-line interface for perms.io. Use it to check permissions, manage permissions, roles, grants and groups, and keep a whole project in a permio.yaml file (plan, apply, export).

It is built for scripts, CI and AI agents as well as people: every command takes --json, exit codes are distinct and documented, and it never prompts when stdin is not a terminal.

$ permio check user_123 /projects/42/documents/7 document.edit --explain
denied: user_123 does not have document.edit on /projects/42/documents/7
  missing on /projects/42/documents/7: document.edit
$ echo $?
1

• Install
• Authentication and configuration
• Concepts
• Commands
• Config as code
• Output, exit codes and errors
• Using with AI agents
• Roadmap
• Development

Install

Not released yet. Once it is:

# Homebrew (macOS, Linux)
brew install perms-io/tap/permio

# npm / npx (downloads the prebuilt binary for your platform)
npx permio-cli --help
npm install -g permio-cli

# Go 1.24+
go install github.com/perms-io/permio-cli/cmd/permio@latest

Prebuilt archives for macOS, Linux and Windows (amd64 and arm64), with a checksums.txt, are attached to each GitHub release.

Shell completion: permio completion bash|zsh|fish|powershell --help explains how to load it.

Authentication and configuration

permio authenticates with a perms.io API key. Create one in the dashboard at app.perms.io. A key belongs to one organisation and one project:

• a check-only key can run checks and read permissions, roles, grants and groups (enough for check, access, list/get, plan and export);
• a full-access key can also create, update and delete them (needed for create, update, delete, grants add/remove, groups members add/remove and apply).

Keys look like perms_ followed by 38 letters and digits, and end in a checksum, so permio rejects a mistyped or truncated key before making any request. Legacy JWT keys are also accepted.

Settings, from highest to lowest precedence:

Setting	Flag	Environment	Profile key	Default
API key	--api-key	PERMIO_API_KEY	api-key	none
API URL	--api-url	PERMIO_API_URL	api-url	api.perms.io:443 (production)
Project	--project	PERMIO_PROJECT	project	default
Profile	--profile	PERMIO_PROFILE	permio config use	default

--api-url accepts host, host:port, https://host[:port], or the alias prod. Production is the only built-in environment; to use another server, give its address.

Profiles

Profiles live in ~/.config/permio/config.yaml (or $XDG_CONFIG_HOME/permio/, or the path in PERMIO_CONFIG). The file is written with 0600 permissions because it holds API keys.

permio config set api-key perms_...                      # default profile
printf '%s' "$KEY" | permio config set api-key -         # read the key from stdin
permio config set --profile staging api-url api.example.com
permio config set --profile staging api-key perms_...
permio config set --profile staging project staging
permio config use staging                                # make staging the current profile
permio config list                                       # profiles (keys redacted) and effective settings
permio config unset --profile staging project
permio config path

# ~/.config/permio/config.yaml
current_profile: staging
profiles:
  default:
    api_key: perms_...
  staging:
    api_key: perms_...
    api_url: api.example.com
    project: staging

permio config list shows where each effective value comes from (flag, env, profile or default), which helps when a command uses an unexpected key.

Concepts

• Permissions are named actions, such as document.read.
• Roles are named sets of permissions. The API identifies roles by ID; the CLI accepts a role's ID or its exact name everywhere.
• Resources are hierarchical URIs such as /projects/42/documents/7. A grant on a URI applies to that URI and everything below it. A _ segment in a granted URI matches any one segment: a grant on /projects/_/public applies to /projects/42/public/readme.
• Grants give a principal (any user or service ID you choose) roles and/or permissions on a resource URI. Granting is additive.
• Groups are named sets of principals. Grant to the principal group:<slug> and every member holds the grant. Groups cannot contain groups.
• A denied check is a normal answer (allowed: false, exit code 1), not an error.

The full documentation is at docs.perms.io (LLM-friendly version).

Commands

Every command has --help with examples. Global flags: --api-key, --api-url, --project, --profile, --json, --quiet/-q, --timeout (per request, default 15s).

This is the beginning of the README. Read the rest at the original. Read the full README ↗