Package Exports

decoupled-cli
decoupled-cli/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (decoupled-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Decoupled Drupal CLI (decoupled-cli)

A command-line interface for managing Decoupled Drupal spaces, monitoring usage, and interacting with the Decoupled Drupal API using personal access tokens.

Installation

npm install -g decoupled-cli

Authentication

Initial Setup

Before using the CLI, you need to authenticate with your Decoupled Drupal personal access token:

decoupled-cli auth login

This will:

Open your browser to the Decoupled Drupal authentication page
Allow you to sign in and create a personal access token
Display the token for you to copy
Prompt you to paste the token in the CLI

Alternatively, you can use manual token entry:

decoupled-cli auth login --manual

This will prompt you for:

API Base URL: Your Decoupled Drupal instance URL (e.g., https://app.drupalcloud.com or http://localhost:3333)
Personal Access Token: Your personal access token (format: dc_tok_...)

The CLI will verify the token and store the credentials securely in your system keychain or config directory.

Environment Variable Authentication (CI/CD)

For automated environments (CI/CD pipelines, GitHub Actions, Docker containers), you can set your Personal Access Token as an environment variable:

export DECOUPLED_CLI_TOKEN=dc_tok_your_token_here

When this environment variable is set, the CLI will automatically use it for authentication without requiring interactive login. This is the recommended approach for:

CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins)
Automated scripts
Docker containers
Any non-interactive environment

Example usage in GitHub Actions:

- name: Run CLI command
  env:
    DECOUPLED_CLI_TOKEN: ${{ secrets.DECOUPLED_CLI_TOKEN }}
  run: |
    npx decoupled-cli spaces list

Priority order for authentication:

DECOUPLED_CLI_TOKEN environment variable (highest priority)
OAuth credentials from .env.local (for Drupal content operations)
Stored token in system keychain
Stored token in config file

Token Management

# View current authentication status
decoupled-cli auth status

# Switch to a different token/instance
decoupled-cli auth login --url https://staging.drupalcloud.com

# Logout (remove stored credentials)
decoupled-cli auth logout

# Test authentication
decoupled-cli auth test

Note: Token creation and management must be done through the web interface at /organization/tokens for security reasons.

Configuration

The CLI stores configuration in ~/.decoupled-cli/config.json:

{
  "currentProfile": "default",
  "profiles": {
    "default": {
      "baseUrl": "https://app.drupalcloud.com",
      "tokenHash": "sha256_hash_of_token"
    },
    "staging": {
      "baseUrl": "https://staging.drupalcloud.com",
      "tokenHash": "sha256_hash_of_token"
    }
  }
}

Actual tokens are stored securely using the system keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service).

Commands

Spaces Management

List Spaces

# List all spaces
decoupled-cli spaces list

# List with additional details
decoupled-cli spaces list --detailed

# Filter by status
decoupled-cli spaces list --status active
decoupled-cli spaces list --status creating
decoupled-cli spaces list --archived

# Output as JSON
decoupled-cli spaces list --json

Get Space Details

# Get space by ID
decoupled-cli spaces get 123

# Get space by name
decoupled-cli spaces get my-space-name

# Output as JSON
decoupled-cli spaces get 123 --json

Create Space

# Create a new space
decoupled-cli spaces create "My New Space" --type pro

# Available types: starter, pro, premium

# With all options
decoupled-cli spaces create "E-commerce Site" \
  --type premium \
  --description "New e-commerce platform"

Update Space

# Update space name
decoupled-cli spaces update 123 --name "Updated Space Name"

# Update space type
decoupled-cli spaces update 123 --type premium

Clone Space

# Clone a space
decoupled-cli spaces clone 123 --name "Cloned Space"

# Clone with different type
decoupled-cli spaces clone 123 --name "Development Copy" --type starter

Archive/Unarchive Space

# Archive a space
decoupled-cli spaces archive 123

# Unarchive a space
decoupled-cli spaces unarchive 123

Delete Space

# Delete a space (with confirmation)
decoupled-cli spaces delete 123

# Force delete without confirmation
decoupled-cli spaces delete 123 --force

Space Operations

# Get Drupal one-time login link
decoupled-cli spaces login 123

# Check if space is ready
decoupled-cli spaces status 123

# Retry space creation (if failed)
decoupled-cli spaces retry 123

# Refresh space usage data
decoupled-cli spaces refresh-usage 123

Usage Monitoring

Organization Usage

# Get overall organization usage
decoupled-cli usage

# Get usage with space breakdown
decoupled-cli usage --breakdown

# Output as JSON
decoupled-cli usage --json

# Get usage for specific date range
decoupled-cli usage --from 2025-01-01 --to 2025-01-31

Space-specific Usage

# Get usage for a specific space
decoupled-cli usage space 123

# Get usage history
decoupled-cli usage space 123 --history

# Export usage data
decoupled-cli usage export --format csv --output usage-report.csv
decoupled-cli usage export --format json --output usage-report.json

Token Management

Token management is not available through the CLI for security reasons.

To create, update, or delete tokens:

Visit the web interface at /organization/tokens
Sign in with your account credentials
Use the token management interface

This ensures tokens can only be managed through secure, authenticated web sessions.

Organization Management

Organization Info

# Get organization details
decoupled-cli org info

# Get organization members
decoupled-cli org members

# Get security settings
decoupled-cli org security

User Management

# List organization users
decoupled-cli users list

# Invite new user
decoupled-cli users invite user@example.com --role developer

# Update user role
decoupled-cli users update 789 --role admin

# Available roles: owner, admin, developer, member

Utility Commands

Health Check

# Check API connectivity
decoupled-cli health

# Verbose health check
decoupled-cli health --verbose

Configuration

# Show current configuration
decoupled-cli config show

# Set configuration values
decoupled-cli config set output json
decoupled-cli config set timeout 30

# Reset configuration to defaults (with confirmation)
decoupled-cli config reset

# Reset configuration to defaults (skip confirmation)
decoupled-cli config reset --confirm

# Available settings:
# - output: table, json, yaml
# - timeout: API request timeout in seconds
# - color: true, false (enable/disable colored output)

Global Options

All commands support these global options:

--profile <name>    # Use specific profile instead of default
--json             # Output response as JSON
--quiet            # Suppress non-essential output
--verbose          # Show detailed output and debug information
--no-color         # Disable colored output
--timeout <seconds> # Override default request timeout

Examples

Daily Workflows

# Check overall status
decoupled-cli usage && decoupled-cli spaces list --status creating

# Create a development environment
decoupled-cli spaces create "Feature Branch Test" --type starter

# Get login link for debugging
decoupled-cli spaces login 123

# Monitor space creation
watch decoupled-cli spaces status 123

# Export monthly usage report
decoupled-cli usage export --format csv --from 2025-01-01 --to 2025-01-31

CI/CD Integration

# Create a dedicated CI token through the web interface at /organization/tokens
# Then use it in CI scripts:
export DECOUPLED_TOKEN="dc_tok_..."
decoupled-cli spaces create "PR-${PR_NUMBER}" --type starter
SPACE_ID=$(decoupled-cli spaces list --json | jq -r '.spaces[] | select(.name=="PR-'${PR_NUMBER}'") | .id')
decoupled-cli spaces status $SPACE_ID

Monitoring Scripts

# Check for spaces stuck in 'creating' status
decoupled-cli spaces list --status creating --json | jq -r '.spaces[] | select((.createdAt | fromnow) > 3600) | .name'

# Get usage alerts
decoupled-cli usage --json | jq -r 'select(.usagePercentages.storage > 80) | "Storage usage: " + (.usagePercentages.storage | tostring) + "%"'

Error Handling

The CLI returns appropriate exit codes:

0: Success
1: General error
2: Authentication error
3: Permission error
4: Not found error
5: Validation error

Environment Variables

DECOUPLED_TOKEN: Override stored token (useful for CI/CD)
DECOUPLED_BASE_URL: Override base URL
DECOUPLED_PROFILE: Use specific profile
DECOUPLED_TIMEOUT: Request timeout in seconds
DECOUPLED_NO_COLOR: Disable colored output

Security

Tokens are stored securely using the system keychain
Sensitive data is never logged or displayed in plain text
API requests use HTTPS with proper authentication headers
Token permissions are validated on each request

Troubleshooting

Common Issues

# Token authentication failed
decoupled-cli auth test
decoupled-cli auth login

# API connectivity issues
decoupled-cli health --verbose

# Permission denied
decoupled-cli tokens list  # Check your token permissions

# Timeout errors
decoupled-cli config set timeout 60

Debug Mode

# Enable debug output
decoupled-cli --verbose spaces list

# Check configuration
decoupled-cli config show

# Test token permissions
decoupled-cli auth test --permissions

API Integration

The CLI directly uses the Decoupled Drupal API with these endpoints:

GET /api/spaces - List spaces
POST /api/spaces - Create space
GET /api/spaces/{id} - Get space details
PATCH /api/spaces/{id} - Update space
DELETE /api/spaces/{id} - Delete space
POST /api/spaces/{id}/clone - Clone space
POST /api/spaces/{id}/archive - Archive space
POST /api/spaces/{id}/unarchive - Unarchive space
GET /api/usage - Get usage data
Token management endpoints (web interface only)

Contributing

The CLI is built with:

Node.js/TypeScript
Commander.js for CLI framework
Axios for HTTP requests
Keytar for secure credential storage
Chalk for colored output
CLI-table3 for formatted tables

For development and contribution guidelines, see the CLI repository.