DrupalCloud CLI (dcloud)

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

Installation

npm install -g dcloud-cli

Authentication

Initial Setup

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

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

dcloud 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
dcloud auth status

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

# Logout (remove stored credentials)
dcloud auth logout

# Test authentication
dcloud 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 ~/.dcloud/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
dcloud spaces list

# List with additional details
dcloud spaces list --detailed

# Filter by status
dcloud spaces list --status active
dcloud spaces list --status creating
dcloud spaces list --archived

# Output as JSON
dcloud spaces list --json

Get Space Details

# Get space by ID
dcloud spaces get 123

# Get space by name
dcloud spaces get my-space-name

# Output as JSON
dcloud spaces get 123 --json

Create Space

# Create a new space
dcloud 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
dcloud spaces create "E-commerce Site" \
  --type premium \
  --template drupalx-decoupled \
  --description "New e-commerce platform"

Update Space

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

# Update space type
dcloud spaces update 123 --type premium

Clone Space

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

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

Archive/Unarchive Space

# Archive a space
dcloud spaces archive 123

# Unarchive a space
dcloud spaces unarchive 123

Delete Space

# Delete a space (with confirmation)
dcloud spaces delete 123

# Force delete without confirmation
dcloud spaces delete 123 --force

Space Operations

# Get Drupal one-time login link
dcloud spaces login 123

# Check if space is ready
dcloud spaces status 123

# Retry space creation (if failed)
dcloud spaces retry 123

# Refresh space usage data
dcloud spaces refresh-usage 123

Usage Monitoring

Organization Usage

# Get overall organization usage
dcloud usage

# Get usage with space breakdown
dcloud usage --breakdown

# Output as JSON
dcloud usage --json

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

Space-specific Usage

# Get usage for a specific space
dcloud usage space 123

# Get usage history
dcloud usage space 123 --history

# Export usage data
dcloud usage export --format csv --output usage-report.csv
dcloud 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
dcloud org info

# Get organization members
dcloud org members

# Get security settings
dcloud org security

User Management

# List organization users
dcloud users list

# Invite new user
dcloud users invite [email protected] --role developer

# Update user role
dcloud users update 789 --role admin

# Available roles: owner, admin, developer, member

Utility Commands

Health Check

# Check API connectivity
dcloud health

# Verbose health check
dcloud health --verbose

Configuration

# Show current configuration
dcloud config show

# Set configuration values
dcloud config set output json
dcloud config set timeout 30

# Reset configuration to defaults (with confirmation)
dcloud config reset

# Reset configuration to defaults (skip confirmation)
dcloud 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
dcloud usage && dcloud spaces list --status creating

# Create a development environment
dcloud spaces create "Feature Branch Test" --type starter --template drupal

# Get login link for debugging
dcloud spaces login 123

# Monitor space creation
watch dcloud spaces status 123

# Export monthly usage report
dcloud 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 DCLOUD_TOKEN="dc_tok_..."
dcloud spaces create "PR-${PR_NUMBER}" --template drupal --type starter
SPACE_ID=$(dcloud spaces list --json | jq -r '.spaces[] | select(.name=="PR-'${PR_NUMBER}'") | .id')
dcloud spaces status $SPACE_ID

Monitoring Scripts

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

# Get usage alerts
dcloud 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

• DCLOUD_TOKEN: Override stored token (useful for CI/CD)
• DCLOUD_BASE_URL: Override base URL
• DCLOUD_PROFILE: Use specific profile
• DCLOUD_TIMEOUT: Request timeout in seconds
• DCLOUD_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
dcloud auth test
dcloud auth login

# API connectivity issues
dcloud health --verbose

# Permission denied
dcloud tokens list  # Check your token permissions

# Timeout errors
dcloud config set timeout 60

Debug Mode

# Enable debug output
dcloud --verbose spaces list

# Check configuration
dcloud config show

# Test token permissions
dcloud 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.