DrupalCloud CLI (decoupled-cli)

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

Installation

npm install -g decoupled-cli

Authentication

Initial Setup

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

decoupled-cli auth login

This will:

1. Open your browser to the DrupalCloud authentication page
2. Allow you to sign in and create a personal access token
3. Display the token for you to copy
4. 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 DrupalCloud 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.

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 --template dcloud

# Available templates: drupal, drupalx, next-drupal, drupalx-decoupled, dcloud
# Available types: starter, pro, premium

# With all options
decoupled-cli spaces create "E-commerce Site" \
  --type premium \
  --template drupalx-decoupled \
  --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:

1. Visit the web interface at /organization/tokens
2. Sign in with your account credentials
3. 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 [email protected] --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 --template drupal

# 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}" --template drupal --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 DrupalCloud 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.