CLI Overview

The porta CLI is the admin tool for managing your Porta identity platform from the command line. It is distributed as a standalone npm package that connects to a running Porta server via the Admin API.

Architecture

The Porta CLI has two components:

Component	Package	Purpose
Standalone CLI	@portaidentity/cli	Full admin tool — 20+ commands, installs via npm
Server CLI	@portaidentity/server	Infrastructure-only — init, migrate, seed, health

The standalone CLI uses the @portaidentity/sdk under the hood, authenticating via OIDC (Auth Code + PKCE) to the Porta server's Admin API. The server CLI uses direct database access for bootstrapping operations.

Installation

Standalone CLI (Recommended)

Install the standalone CLI globally to manage any Porta server:

# Install globally
npm install -g @portaidentity/cli

# Or use npx
npx @portaidentity/cli <command>

# Verify installation
porta version

Server CLI (Docker / Development)

The server image includes infrastructure-only commands. In Docker:

# Via docker exec
docker exec -it porta-app porta init
docker exec -it porta-app porta migrate up

# Via the porta.sh wrapper script
./porta init
./porta migrate up

In development:

yarn porta init
yarn porta migrate up

Authentication

The standalone CLI authenticates using OIDC Authorization Code flow with PKCE:

# Login (opens browser for authentication)
porta login

# Login with explicit server URL
porta login --server https://porta.example.com:3443

# Check current identity
porta whoami

# Logout
porta logout

Credentials are stored at ~/.porta/credentials.json with 0600 permissions.

Interactive Administration Shell

Open the terminal administration shell against an operator-owned HTTPS server:

porta admin --server https://identity.example.com

The shell requires interactive stdin and stdout, so it cannot be combined with --json or --force. It uses the CLI's browser-based OIDC Authorization Code with PKCE flow, with the manual authorization URL and callback flow available when a browser cannot be opened.

After authentication, choose an organization from the complete Organizations list; the shell never selects one automatically. The Organizations menu can switch context or create an organization from its name, optional slug, and optional default locale. A successfully created organization is selected immediately. The selection lasts only for the running shell and does not reauthenticate or grant additional access.

Without a verified session, porta admin opens a blocking Authentication required dialog. Authenticate is focused and starts the existing browser/manual OIDC flow with Enter or a mouse click; Quit is the only alternative. Cancellation or a failed attempt returns to the same dialog.

Press F10 to open the hamburger menu containing Who am I…, Reauthenticate, and Quit. Who am I… shows the verified identity and server details. The Users menu becomes available after an organization is selected. It supports browsing, searching, filtering, creating, and inviting users; selecting a row opens profile, account, history, credential, and lifecycle actions allowed by the verified permissions. Use Ctrl-R to reauthenticate; changing to another server requires explicit credential-replacement confirmation. Using --insecure disables TLS certificate validation and leaves a persistent warning in the shell.

Global Options

Every standalone CLI command supports these global flags:

Flag	Description
--server <url>	Porta server URL (or set PORTA_SERVER env var)
--json	Output results as JSON instead of formatted tables
--verbose	Enable verbose/debug logging
--force	Skip confirmation prompts
--insecure	Allow self-signed TLS certificates

Server CLI commands support:

Flag	Description
--database-url	Override DATABASE_URL
--redis-url	Override REDIS_URL

Output Formatting

By default, list and show commands render results as formatted tables. Table cells are never truncated — full values, including complete UUIDs, are always printed so they can be copied directly into other commands (e.g. porta client show <full-id>).

When a table is wider than the terminal, columns are sized to fit and long values wrap onto multiple lines within their cell rather than being clipped. When output is piped or redirected (no TTY), each value is printed on a single line for easy grep/awk processing. Use --json for fully machine-readable output.

Command Reference

Standalone CLI (@portaidentity/cli)

Command	Description
porta login	Authenticate via OIDC (browser-based)
porta logout	Clear stored credentials
porta whoami	Display current identity
porta admin	Open the interactive verified-session administration shell
porta version	Show CLI, SDK, and server version info
porta org	Manage organizations (CRUD, status, branding, delete)
porta app	Manage applications, modules, roles, permissions, claims
porta client	Manage OIDC clients and secrets
porta user	Manage users (CRUD, status, password, roles, claims, 2FA)
porta keys	Manage ES256 signing keys
porta config	Manage system configuration
porta audit	View audit log entries
porta health	Check server health (via API)
porta exports download	Bounded allowlisted CSV/JSON administrative export
porta export manifest	Export a selective environment-transfer manifest
porta import manifest	Preview and apply a strict portability manifest

Server CLI (Infrastructure Only)

These commands are available inside the Porta Docker container or development environment:

Command	Description
porta init	Bootstrap admin infrastructure (direct-DB)
porta migrate	Run database migrations (up/down/status)
porta seed	Load development seed data
porta health	Check DB + Redis connectivity (direct)
porta user 2fa	Admin 2FA status/disable/reset (direct-DB)

Detailed Documentation

• Bootstrap & Authentication — porta init, porta login, porta logout
• Organizations — porta org subcommands
• Applications — porta app and nested subcommands
• Clients — porta client and secret management
• Users — porta user with status, password, roles, claims, 2FA
• Infrastructure — porta migrate, porta seed, porta health
• Environment Portability — Selective manifest export and preview-first import