### Pragma CLI Quick Start Commands

Source: https://github.com/pragmatiks/pragma-cli/blob/main/README.md

This snippet shows essential commands for getting started with Pragma CLI, including authentication, applying a resource, and checking resource status. These commands are fundamental for initial setup and basic operations.

```bash
# Authenticate
pragma auth login

# Apply a resource
pragma resources apply bucket.yaml

# Check status
pragma resources get gcp/storage my-bucket
```

--------------------------------

### Install Pragma CLI

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Installs the Pragma CLI using package managers like pip or uv. It also shows how to enable shell completion for enhanced user experience.

```bash
# Install with pip
pip install pragmatiks-cli

# Or install with uv
uv add pragmatiks-cli

# Enable shell completion for tab completion support
pragma --install-completion
```

--------------------------------

### Pragma CLI Resource Application Example

Source: https://github.com/pragmatiks/pragma-cli/blob/main/README.md

Demonstrates how to define a resource in a YAML file and apply it using the Pragma CLI. It covers applying single files, multiple files, and applying with a pending flag for immediate execution.

```yaml
# bucket.yaml
provider: gcp
resource: storage
name: my-bucket
config:
  location: US
  storage_class: STANDARD
```

```bash
# Apply from file
pragma resources apply bucket.yaml

# Apply multiple files
pragma resources apply *.yaml

# Apply with pending flag to execute immediately
pragma resources apply --pending bucket.yaml
```

--------------------------------

### Pragma CLI Installation

Source: https://github.com/pragmatiks/pragma-cli/blob/main/README.md

Instructions for installing the Pragma CLI using pip and uv. It also includes a command to enable shell completion for enhanced user experience.

```bash
pip install pragmatiks-cli
```

```bash
uv add pragmatiks-cli
```

```bash
pragma --install-completion
```

--------------------------------

### Pragma CLI Resource Listing and Getting

Source: https://github.com/pragmatiks/pragma-cli/blob/main/README.md

Shows commands for listing all resources, filtering them by provider or resource type, and retrieving details of a specific resource. These commands are essential for monitoring and inspecting managed resources.

```bash
# List all resources
pragma resources list

# Filter by provider
pragma resources list --provider gcp

# Filter by resource type
pragma resources list --resource storage

# Get specific resource
pragma resources get gcp/storage my-bucket
```

--------------------------------

### Initialize Provider Project with pragma provider init

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Initializes a new provider project with a complete directory structure. Supports specifying output directory, defaults, description, author, and email.

```bash
# Initialize a new provider project
pragma provider init mycompany

# Specify output directory
pragma provider init postgres --output ./providers/postgres

# Use defaults without prompts
pragma provider init mycompany --defaults --description "My custom provider"

# With all options
pragma provider init mycompany \
  --output ./my-provider \
  --description "My custom provider" \
  --author "John Doe" \
  --email "john@example.com"
```

--------------------------------

### Pragma CLI Provider Development Commands

Source: https://github.com/pragmatiks/pragma-cli/blob/main/README.md

Illustrates the commands used for developing custom providers with Pragma CLI, including initializing a new provider project, syncing schemas, and building/deploying the provider.

```bash
# Initialize a new provider project
pragma provider init mycompany

# Sync resource schemas with the platform
pragma provider sync

# Build and deploy
pragma provider push --deploy
```

--------------------------------

### List Pragma CLI Contexts

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Lists all available contexts configured in the Pragma CLI, displaying their names and corresponding API URLs. This helps in managing different deployment environments.

```bash
pragma config get-contexts

# Expected output:
# Available contexts:
# * default: https://api.pragmatiks.io
#   production: https://api.prod.pragmatiks.io
#   staging: https://api.staging.pragmatiks.io
```

--------------------------------

### Pragma CLI Configuration with Environment Variables

Source: https://github.com/pragmatiks/pragma-cli/blob/main/README.md

Shows how to configure the Pragma CLI by setting environment variables for the API URL and authentication token. This is useful for customizing the CLI's behavior and connecting to specific instances.

```bash
export PRAGMA_API_URL=https://api.pragmatiks.io
export PRAGMA_AUTH_TOKEN=sk_...
```

--------------------------------

### List Provider Build History with pragma provider builds

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Lists the build history for a given provider. It displays the version, status, creation timestamp, and any errors for each build.

```bash
pragma provider builds postgres
```

--------------------------------

### Manage Resources with Pragma CLI

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Handles declarative management of cloud resources using YAML manifests. Supports applying resources from files, listing resources with filters, retrieving specific resources, and deleting resources.

```yaml
# bucket.yaml - Resource manifest example
provider: gcp
resource: storage
name: my-bucket
config:
  location: US
  storage_class: STANDARD
```

```bash
# Apply a single resource file
pragma resources apply bucket.yaml

# Apply multiple files using glob pattern
pragma resources apply *.yaml

# Apply with immediate processing (skip DRAFT state)
pragma resources apply --pending bucket.yaml

# Expected output:
# Applied gcp/storage/my-bucket [pending]
```

```yaml
# secret.yaml - Secret with file reference
provider: pragma
resource: secret
name: api-keys
config:
  data:
    private_key: "@./keys/private.pem"  # File contents are inlined
    api_token: "sk_live_abc123"
```

```bash
# List all resources
pragma resources list

# Filter by provider
pragma resources list --provider gcp

# Filter by resource type
pragma resources list --resource storage

# Filter by tags
pragma resources list --tag environment:production --tag team:backend

# Expected output:
gcp/storage/my-bucket [active]
gcp/compute/web-server [pending]
aws/s3/data-lake [active]
```

```bash
# Get all resources of a type
pragma resources get gcp/storage

# Get a specific resource by name
pragma resources get gcp/storage my-bucket

# Expected output:
gcp/storage/my-bucket [active]
```

```bash
# Delete a resource
pragma resources delete gcp/storage my-bucket

# Expected output:
# Deleted gcp/storage/my-bucket
```

--------------------------------

### Build and Push Provider Code with pragma provider push

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Builds and pushes provider code to the platform. It creates a tarball of the source directory and uploads it for container building. Options include building only, immediate deployment, streaming logs, and asynchronous builds.

```bash
# Build only (wait for completion)
pragma provider push

# Build and deploy immediately
pragma provider push --deploy

# Build with streaming logs
pragma provider push --logs

# Build without waiting (async)
pragma provider push --no-wait

# Build and deploy with logs
pragma provider push --logs --deploy

# Specify source directory
pragma provider push --directory ./my-provider --package my_provider
```

--------------------------------

### Sync Provider Resources with pragma provider sync

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Discovers resources in the provider package and registers their schemas with the platform API. Supports syncing from the current directory, a specific package, and previewing changes without making them.

```bash
# Sync resources from current directory
pragma provider sync

# Sync specific package
pragma provider sync --package postgres_provider

# Preview without making changes
pragma provider sync --dry-run
```

--------------------------------

### Deploy Provider with pragma provider deploy

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Deploys a provider from a pre-built container image. Supports specifying the image directly or overriding the package name during deployment.

```bash
# Deploy a specific image
pragma provider deploy --image europe-west4-docker.pkg.dev/project/repo/provider:tag

# Deploy with package name override
pragma provider deploy -i provider:latest --package my_provider
```

--------------------------------

### Pragma CLI Token Discovery Precedence (Bash)

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Understand the order in which the Pragma CLI discovers authentication tokens, from highest to lowest priority. This includes explicit flags, environment variables (context-specific and default), credential files, and unauthenticated requests.

```bash
# Token discovery order (highest to lowest priority):
# 1. --token flag (explicit override)
pragma resources list --token sk_explicit_token

# 2. PRAGMA_AUTH_TOKEN_<CONTEXT> context-specific environment variable
export PRAGMA_AUTH_TOKEN_PRODUCTION=sk_prod_token

# 3. PRAGMA_AUTH_TOKEN environment variable
export PRAGMA_AUTH_TOKEN=sk_default_token

# 4. ~/.config/pragma/credentials file (from pragma auth login)
# Stored automatically after successful login

# 5. No authentication (unauthenticated requests)
```

--------------------------------

### Show Current Pragma CLI Context

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Displays the currently active context and its associated API URL. Useful for verifying which environment the CLI is currently targeting.

```bash
pragma config current-context

# Expected output:
# Current context: default
# API URL: https://api.pragmatiks.io
```

--------------------------------

### Configure Pragma CLI Context

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Creates a new context or updates an existing one with a specified API URL. Allows for easy management of different API endpoints.

```bash
pragma config set-context staging --api-url https://api.staging.pragmatiks.io

# Expected output:
# ✓ Context 'staging' configured
```

--------------------------------

### List Deployed Providers with pragma provider list

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Lists all deployed providers along with their version, status, and last deployed timestamp. Displays information in a formatted table.

```bash
pragma provider list
```

--------------------------------

### Pragma CLI Development Commands

Source: https://github.com/pragmatiks/pragma-cli/blob/main/README.md

Lists commands used during the development of the Pragma CLI itself, including running tests, formatting code, and performing type checking and linting. These commands ensure code quality and maintainability.

```bash
# Run tests
task cli:test

# Format code
task cli:format

# Type check and lint
task cli:check
```

--------------------------------

### Pragma CLI Authentication Commands

Source: https://github.com/pragmatiks/pragma-cli/blob/main/README.md

Contains commands for managing user authentication with Pragma CLI, including logging in (which opens a browser), checking the current logged-in user, and logging out.

```bash
# Login (opens browser)
pragma auth login

# Check current user
pragma auth whoami

# Logout
pragma auth logout
```

--------------------------------

### Delete Provider and Resources with Pragma CLI

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Deletes a provider and optionally all associated resources. The `--cascade` flag is used to remove all resources, while `--force` bypasses confirmation prompts. Use with caution as it's a destructive operation.

```bash
# Delete provider (fails if has resources)
pragma provider delete postgres

# Delete provider and all resources
pragma provider delete postgres --cascade

# Skip confirmation
pragma provider delete postgres --cascade --force

# Expected output:
# Provider: postgres
# Warning: --cascade will delete all resources for this provider
#
# Are you sure you want to DELETE provider and all its resources? [y/N]: y
#
# Provider deleted: postgres
#
# ┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
# ┃ Component                ┃  Deleted ┃
# ┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
# │ Builds Cancelled         │        0 │
# │ Source Archives          │        2 │
# │ Deployment               │      Yes │
# │ Resources                │       15 │
# │ Resource Definitions     │        3 │
# │ Outbox Events            │        0 │
# │ Dead Letter Events       │        2 │
# │ NATS Messages Purged     │       42 │
# │ NATS Consumer            │  Deleted │
# └──────────────────────────┴──────────┘
```

--------------------------------

### Pragma CLI Authentication

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Manages authentication with the Pragmatiks platform. Includes logging in via browser-based Clerk authentication, checking current authentication status, and logging out.

```bash
# Login to default context (opens browser)
pragma auth login

# Login to a specific context
pragma auth login --context production

# Expected output:
# Authenticating for context: default
# API URL: https://api.pragmatiks.io
# 
# Opening browser to: https://app.pragmatiks.io
# 
# Waiting for authentication...
# ✓ Successfully authenticated!
# Credentials saved to /home/user/.config/pragma/credentials
```

```bash
pragma auth whoami

# Expected output:
# Authentication Status
#
# * default: ✓ Authenticated
#   production: Not authenticated
```

```bash
# Logout from current context
pragma auth logout

# Logout from specific context
pragma auth logout --context staging

# Logout from all contexts
pragma auth logout --all

# Expected output:
# ✓ Cleared credentials for current context 'default'
```

--------------------------------

### Manage Resource Types with Pragma CLI

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Enables registration and unregistration of custom resource types within the Pragma platform. This allows users to define and manage new types of resources using JSON schemas.

```bash
# Register a resource type with JSON schema
pragma resources register mycompany/database \
  --description "Custom database resource" \
  --schema schema.json \
  --tag category:data

# Register without schema
pragma resources register mycompany/cache --description "Cache instance"

# Expected output:
# Registered mycompany/database
```

```bash
pragma resources unregister mycompany/database

# Expected output:
# Unregistered mycompany/database
```

--------------------------------

### Update Provider Project with Pragma CLI

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Updates an existing provider project by applying the latest template changes using Copier's 3-way merge. Can update the current directory or a specific project path.

```bash
# Update current directory
pragma provider update

# Update specific directory
pragma provider update ./my-provider

# Expected output:
# Updating provider project: ./my-provider
#
# Provider project updated successfully.
```

--------------------------------

### Switch Pragma CLI Context

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Switches the active context for the Pragma CLI to a different, pre-configured context. This changes the target API endpoint for subsequent commands.

```bash
pragma config use-context production

# Expected output:
# ✓ Switched to context 'production'
```

--------------------------------

### Check Provider Status with pragma provider status

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Checks the deployment status of a specific provider. It returns details such as status, replicas, version, image, and last updated time.

```bash
pragma provider status postgres
```

--------------------------------

### Rollback Provider Version with Pragma CLI

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Rolls back a specified provider to a previous version. Supports rolling back to a specific version or the last successful version. This command is crucial for reverting changes that may have introduced issues.

```bash
# Rollback to specific version
pragma provider rollback postgres --version 20250114.120000

# Rollback to previous successful version
pragma provider rollback postgres

# Expected output:
# Rolling back provider: postgres
# Target version: 20250114.120000
#
# Rollback initiated: postgres
# Status: progressing
```

--------------------------------

### List Dead Letter Events with Pragma CLI

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Lists dead letter events, which represent failed resource operations that exceeded retry limits. Supports filtering by provider. Output includes event details and failure timestamps.

```bash
# List all dead letter events
pragma ops dead-letter list

# Filter by provider
pragma ops dead-letter list --provider postgres

# Expected output:
# ┏━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
# ┃ Event ID     ┃ Provider ┃ Resource Type ┃ Resource Name ┃ Error Message       ┃ Failed At           ┃
# ┡━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
# │ evt_abc123   │ postgres │ database      │ mydb          │ Connection refused  │ 2025-01-14 10:00:00 │
# │ evt_def456   │ gcp      │ storage       │ bucket-1      │ Permission denied...│ 2025-01-14 11:00:00 │
# └──────────────┴──────────┴───────────────┴───────────────┴─────────────────────┴─────────────────────┘
```

--------------------------------

### Show Dead Letter Event Details with Pragma CLI

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Shows detailed information about a specific dead letter event using its Event ID. The output is typically in JSON format and includes all relevant data about the failed operation.

```bash
pragma ops dead-letter show evt_abc123

# Expected output (JSON):
# {
#   "id": "evt_abc123",
#   "provider": "postgres",
#   "resource_type": "database",
#   "resource_name": "mydb",
#   "error_message": "Connection refused to database host",
#   "failed_at": "2025-01-14T10:00:00Z",
#   "retry_count": 3,
#   "payload": { ... }
# }
```

--------------------------------

### Pragma CLI Resource Deletion

Source: https://github.com/pragmatiks/pragma-cli/blob/main/README.md

Provides the command to delete a specific resource managed by Pragma CLI. This is a crucial operation for resource lifecycle management.

```bash
pragma resources delete gcp/storage my-bucket
```

--------------------------------

### Delete Pragma CLI Context

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Deletes a specified context configuration from the Pragma CLI settings. This removes the context and its associated API URL.

```bash
pragma config delete-context staging

# Expected output:
# ✓ Context 'staging' deleted
```

--------------------------------

### Retry Dead Letter Events with Pragma CLI

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Retries failed dead letter events. Supports retrying a single event by its ID or retrying all pending events. This is used to re-attempt operations that previously failed.

```bash
# Retry a single event
pragma ops dead-letter retry evt_abc123

# Retry all dead letter events
pragma ops dead-letter retry --all

# Expected output:
# Retried event: evt_abc123
# or
# Retry 5 event(s)? [y/N]: y
# Retried 5 event(s)
```

--------------------------------

### Delete Dead Letter Events with Pragma CLI

Source: https://context7.com/pragmatiks/pragma-cli/llms.txt

Deletes dead letter events. Supports deleting a single event by ID, all events for a specific provider, or all dead letter events. This action permanently removes event records.

```bash
# Delete a single event
pragma ops dead-letter delete evt_abc123

# Delete all events for a provider
pragma ops dead-letter delete --provider postgres

# Delete all events
pragma ops dead-letter delete --all

# Expected output:
# [Success message indicating deletion]
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.