# pmctl

pmctl is a CLI tool for managing Postman collections, environments, and workspaces from the terminal. While the official Postman CLI only supports running collections, pmctl wraps the Postman API to provide full browsing, inspection, and management capabilities. It supports multi-profile management for users with multiple Postman accounts.

The tool features rich terminal output with colored tables and tree views powered by Rich, fuzzy search for finding requests across collections, and JSON output mode for scripting and automation. It integrates with AI coding tools through skill definitions for Claude Code, Cursor, OpenAI Codex, and ClawHub.

## Profile Management

### Add a Profile

Add a new Postman API profile with your API key. Get your key from https://go.postman.co/settings/me/api-keys.

```bash
# Add profile with API key and set as default
pmctl profile add personal --api-key "PMAK-xxx-yyy" --label "Personal Account" --default

# Add additional work profile
pmctl profile add work --api-key "PMAK-aaa-bbb" --label "Work Account"
```

### List Profiles

Display all configured profiles with their settings.

```bash
# List all profiles (shows masked API keys)
pmctl profile list

# JSON output for scripting
pmctl profile list --json
```

### Switch Default Profile

Change which profile is used by default for all commands.

```bash
# Switch to work profile
pmctl profile switch work

# Use specific profile for single command
pmctl collections list --profile personal
```

### Set Default Workspace

Configure a default workspace ID to scope list commands automatically.

```bash
# Set default workspace for current profile
pmctl profile set-workspace "workspace-id-123"

# Set for specific profile
pmctl profile set-workspace "workspace-id-456" --profile work
```

### Show Current User

Display information about the authenticated user for the active profile.

```bash
# Show current user info
pmctl profile whoami

# JSON output
pmctl profile whoami --json
# Output: {"user": {"email": "user@example.com", "fullName": "John Doe", "teamName": "My Team"}}
```

### Remove a Profile

Delete a profile from the configuration.

```bash
pmctl profile remove old-profile
```

## Workspaces

### List Workspaces

Retrieve all accessible Postman workspaces.

```bash
# List all workspaces
pmctl workspaces list

# Filter by name
pmctl workspaces list --search "api"

# JSON output for scripting
pmctl workspaces list --json
```

## Collections

### List Collections

Display collections, optionally filtered by workspace.

```bash
# List collections in default workspace
pmctl collections list

# List from all workspaces
pmctl collections list --all

# Filter by specific workspace
pmctl collections list --workspace "workspace-id"

# JSON output
pmctl collections list --json
```

### Show Collection Tree

Display all requests in a collection as a hierarchical tree view.

```bash
# Show collection structure by UID
pmctl collections show "12345678-abcd-efgh-ijkl-mnopqrstuvwx"

# JSON output with full collection data
pmctl collections show "12345678-abcd-efgh-ijkl-mnopqrstuvwx" --json
```

## Requests

### List Requests

Display all requests in a collection as a flat table with method, name, path, and URL.

```bash
# List by collection name (case-insensitive)
pmctl requests list --collection "My API"

# List by collection UID
pmctl requests list -c "12345678-abcd-efgh"

# Fuzzy search (characters matched in order: "crtUsr" matches "Create User")
pmctl requests list -c "My API" --search "getUser"

# JSON output for scripting
pmctl requests list -c "My API" --json
# Output: [{"name": "Get User", "path": "Users/Get User", "method": "GET", "url": "{{base-url}}/v1/users/:userId"}]
```

### Show Request Details

Inspect a specific request including headers, query params, path variables, and body.

```bash
# Show request by name (case-insensitive substring match)
pmctl requests show "Create User" --collection "My API"

# JSON output with full request details
pmctl requests show "Create User" -c "My API" --json
# Output includes: method, url, headers, query params, path variables, body
```

## Environments

### List Environments

Display all environments, optionally filtered by workspace.

```bash
# List environments in default workspace
pmctl environments list

# List from all workspaces
pmctl environments list --all

# JSON output
pmctl environments list --json
```

### Show Environment Variables

Display environment variables by name or ID. Sensitive values are automatically masked.

```bash
# Show by name
pmctl environments show "Production"

# Show by ID
pmctl environments show "env-id-123"

# Full values without truncation
pmctl environments show "Production" --full

# JSON output (includes unmasked secrets - useful for scripting)
pmctl environments show "Production" --json
# Output: {"name": "Production", "values": [{"key": "base-url", "value": "https://api.example.com", "type": "default"}]}
```

## Shell Completion

### Generate Completion Scripts

Enable tab completion for bash, zsh, or fish shells.

```bash
# Bash - add to ~/.bashrc
eval "$(pmctl completion bash)"

# Zsh - add to ~/.zshrc
eval "$(pmctl completion zsh)"

# Fish - save to completions directory
pmctl completion fish > ~/.config/fish/completions/pmctl.fish
```

## Python API

### PostmanClient Class

Use the PostmanClient directly in Python scripts for programmatic access.

```python
from pmctl.api import PostmanClient

# Create client with API key
with PostmanClient("PMAK-xxx-yyy") as client:
    # Get current user info
    me = client.get_me()
    print(f"Logged in as: {me['user']['email']}")

    # List workspaces
    workspaces = client.list_workspaces()
    for ws in workspaces:
        print(f"{ws['name']} ({ws['id']})")

    # List collections in a workspace
    collections = client.list_collections(workspace_id="workspace-123")

    # Get full collection with all requests
    collection = client.get_collection("collection-uid")

    # List and get environments
    environments = client.list_environments(workspace_id="workspace-123")
    env = client.get_environment("env-id")
    print(f"Base URL: {env['values'][0]['value']}")
```

### Configuration Management

Programmatically manage profiles and configuration.

```python
from pmctl.config import (
    load_config,
    add_profile,
    remove_profile,
    set_default_profile,
    set_profile_workspace
)

# Add a new profile
config = add_profile(
    name="work",
    api_key="PMAK-xxx-yyy",
    label="Work Account",
    set_default=True
)

# Load existing configuration
config = load_config()
profile = config.get_profile("work")  # or default if None
print(f"Using API key: {profile.api_key[:12]}...")

# Set default workspace for a profile
set_profile_workspace("work", "workspace-id-123")

# Switch default profile
set_default_profile("personal")

# Remove a profile
remove_profile("old-profile")
```

## Workflow Examples

### Resolve Full API URL from Postman Variables

Postman requests use `{{variable}}` placeholders. Resolve them by combining request data with environment values.

```bash
# 1. Get request details (shows URL like {{base-url}}/v1/users/:userId)
pmctl requests show "Get User" -c "My API" --json | jq '.[0].request.url.raw'

# 2. Get environment variable value
pmctl environments show "Production" --json | jq -r '.values[] | select(.key == "base-url") | .value'

# 3. Combine in a script
BASE=$(pmctl environments show "Production" --json | jq -r '.values[] | select(.key == "base-url") | .value')
# Replace {{base-url}} with actual value and :userId with real ID
echo "${BASE}/v1/users/12345"
```

### Construct curl Command from Postman Request

Extract request details to build executable curl commands.

```bash
# Get full request as JSON
REQ=$(pmctl requests show "Create User" -c "My API" --json)

# Extract components
echo "$REQ" | jq '.[0].request | {
  method,
  url: .url.raw,
  headers: .header,
  body: .body.raw
}'

# Build curl command
METHOD=$(echo "$REQ" | jq -r '.[0].request.method')
URL=$(echo "$REQ" | jq -r '.[0].request.url.raw')
BODY=$(echo "$REQ" | jq -r '.[0].request.body.raw // empty')

curl -X "$METHOD" "$URL" \
  -H "Content-Type: application/json" \
  -d "$BODY"
```

## Configuration File

Profiles are stored in `~/.config/pmctl/config.toml` with the following structure.

```toml
default_profile = "work"

[profiles.personal]
api_key = "PMAK-personal-key"
label = "personal@example.com"

[profiles.work]
api_key = "PMAK-work-key"
label = "work@company.com"
workspace = "your-workspace-id"
```

## Summary

pmctl serves developers and DevOps engineers who need command-line access to Postman resources. Primary use cases include browsing API collections without opening the GUI, scripting API discovery workflows with JSON output piped to jq, managing multiple Postman accounts (personal and work) through profiles, and integrating with CI/CD pipelines for API documentation or testing setup.

The tool integrates seamlessly with AI coding assistants through skill definitions, enabling agents to discover API endpoints, look up request details, and construct curl commands from Postman data. Install via `pip install pmctl`, configure a profile with your Postman API key, and start browsing your collections from the terminal.