Decoupled Drupal CLI (decoupled-cli)

A command-line interface for managing Decoupled Drupal spaces, monitoring usage, and enabling AI assistants to interact with your platform through the Model Context Protocol (MCP).

Features

• 🔐 Secure Authentication - OAuth (Google/GitHub) and Personal Access Tokens
• 🤖 AI Integration - Model Context Protocol support for Claude Code and Cursor
• 📦 Space Management - Create, clone, delete, and monitor Drupal spaces
• 📊 Usage Monitoring - Track storage, bandwidth, and API requests
• 📥 Content Import - Import content models and data to Drupal

Installation

Option 1: Global Installation

npm install -g decoupled-cli

Option 2: Use with npx (No Installation Required)

You can run the CLI without installing it globally using npx:

npx decoupled-cli@latest auth login
npx decoupled-cli@latest spaces list
npx decoupled-cli@latest mcp configure

Benefits:

• ✅ Always runs the latest version
• ✅ No global installation needed
• ✅ Perfect for quick setup or one-time use
• ✅ Works great in CI/CD environments

Authentication

Initial Setup

Authentication is a simple two-step process:

Step 1: Sign in to your dashboard

# With global installation
decoupled-cli auth login

# With npx (no installation)
npx decoupled-cli@latest auth login

This will open your browser where you can sign in with Google or GitHub.

Step 2: Generate CLI token

After signing in, generate your Personal Access Token:

# With global installation
decoupled-cli auth token

# With npx (no installation)
npx decoupled-cli@latest auth token

This will:

1. Open your browser to the CLI authorization page
2. Display your Personal Access Token
3. Prompt you to copy and paste the token
4. Verify and securely store your credentials

Alternative: Manual Token Entry

If you already have a token, you can enter it directly:

decoupled-cli auth login --manual
# or with npx
npx decoupled-cli@latest auth login --manual

This will prompt you for:

• API Base URL: Your Decoupled instance URL (default: https://dashboard.decoupled.io)
• 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:

1. DECOUPLED_CLI_TOKEN environment variable (highest priority)
2. Stored token in system keychain
3. Stored token in config file

Note: Content import operations use the same PAT token - no separate OAuth configuration needed!

Proxy Support

The CLI automatically respects HTTP/HTTPS proxy environment variables for environments that require proxy access (corporate networks, CI/CD platforms like Claude Web, etc.):

export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080

The CLI checks for proxy configuration in this order:

1. HTTPS_PROXY (case-sensitive)
2. https_proxy (lowercase)
3. HTTP_PROXY (case-sensitive)
4. http_proxy (lowercase)

When a proxy is detected, the CLI will automatically route all API requests through it. This is particularly useful for:

• Corporate environments with egress proxies
• CI/CD platforms that use proxies (Claude Web, GitHub Actions with proxies)
• Development environments with SSL inspection proxies

No configuration is required - just set the environment variable and the CLI will automatically use the proxy.

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).

AI Integration with MCP

The CLI supports the Model Context Protocol (MCP), enabling AI assistants in Claude Code and Cursor to manage your Drupal spaces using natural language.

Setup

With global installation:

# Log in first (if not already)
decoupled-cli auth login

# Configure MCP for Claude Code
decoupled-cli mcp configure --ide claude-code

# Or configure for Cursor
decoupled-cli mcp configure --ide cursor

With npx (no installation):

# Quick two-step setup
npx decoupled-cli@latest auth login
npx decoupled-cli@latest mcp configure --ide claude-code

After configuration, restart your IDE and you can interact with your platform naturally:

Example conversations:

You: "Show me all my Drupal spaces"
AI: Lists all your spaces with status and URLs

You: "Create a blog space called Tech News"
AI: Creates the space and returns the ID and URL

You: "What's my current storage usage?"
AI: Shows organization-wide usage statistics

You: "Clone space 5 and name it Staging"
AI: Clones the space with all content

Available MCP Commands

# Configure MCP for an IDE
decoupled-cli mcp configure [--ide <claude-code|cursor>]

# Create project-level .mcp.json (for Claude Code web/CLI)
decoupled-cli mcp configure --project

# Show configuration status
decoupled-cli mcp status

# Remove MCP configuration
decoupled-cli mcp remove

# Show config without writing (for manual setup)
decoupled-cli mcp configure --show-only

Project-Level MCP Configuration

For teams or when using Claude Code on the web, you can create a project-level .mcp.json that uses environment variables:

npx decoupled-cli@latest mcp configure --project

This creates a .mcp.json in your project that references DECOUPLED_API_TOKEN:

{
  "mcpServers": {
    "decoupled-io": {
      "type": "http",
      "url": "https://mcp.decoupled.io",
      "headers": {
        "Authorization": "Bearer ${DECOUPLED_API_TOKEN}"
      }
    }
  }
}

Team members just need to set their token:

export DECOUPLED_API_TOKEN="dc_tok_your_token_here"

What AI Can Do

• Read Operations:

  • List all spaces with details
  • Get space information
  • View usage statistics
  • Check organization details

• Write Operations:

  • Create new spaces
  • Clone existing spaces
  • Delete spaces
  • Import content models and data

All operations use your existing authentication and permissions.

Commands

Note: All commands below assume global installation. If using npx, prefix each command with npx decoupled-cli@latest, for example: npx decoupled-cli@latest spaces list

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

Content Management

Import Content

# Import content model and data from JSON file
decoupled-cli content import --file content-import.json

# Preview import without applying changes
decoupled-cli content import --file content-import.json --preview

# Show example import JSON structure
decoupled-cli content import --example

Import JSON Format:

{
  "model": [
    {
      "bundle": "blog_post",
      "label": "Blog Post",
      "description": "Blog article content type",
      "body": true,
      "fields": [
        {
          "id": "subtitle",
          "label": "Subtitle",
          "type": "string"
        },
        {
          "id": "featured_image",
          "label": "Featured Image",
          "type": "image"
        }
      ]
    }
  ],
  "content": [
    {
      "id": "post1",
      "type": "node.blog_post",
      "path": "/blog/my-first-post",
      "values": {
        "title": "My First Post",
        "body": "<p>Post content here</p>",
        "subtitle": "An introduction"
      }
    }
  ]
}

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

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

Space Management:

• 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

Content Operations:

• POST /api/spaces/{id}/content-import - Import content model and data

Usage & Monitoring:

• GET /api/usage - Get usage data
• GET /api/organization - Get organization details

MCP (Model Context Protocol):

• Production: https://mcp.decoupled.io (Nginx proxy to Vercel)
• Local: http://localhost:3333/api/mcp
• GET - Server information endpoint
• POST - HTTP transport for JSON-RPC 2.0 messages

Authentication:

• Token management endpoints (web interface only at /organization/tokens)

Contributing

The CLI is built with:

• Node.js/TypeScript - Core runtime and type safety
• Commander.js - CLI framework and command parsing
• Inquirer - Interactive prompts
• Axios - HTTP requests for API calls
• Keytar - Secure credential storage (system keychain)
• Chalk - Colored terminal output
• CLI-table3 - Formatted table output
• Open - Cross-platform browser opening

Development

# Clone repository
git clone https://github.com/nextagencyio/decoupled-dashboard.git
cd decoupled-dashboard/cli

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run locally
npm start -- [command]

# Watch mode for development
npm run dev

Project Structure

cli/
├── src/
│   ├── commands/        # CLI command implementations
│   │   ├── auth.ts           # Authentication commands
│   │   ├── auth-interactive.ts # OAuth flow
│   │   ├── spaces.ts         # Space management
│   │   ├── content.ts        # Content import
│   │   ├── mcp.ts            # MCP configuration
│   │   ├── usage.ts          # Usage statistics
│   │   ├── org.ts            # Organization management
│   │   ├── health.ts         # Health checks
│   │   └── config.ts         # CLI configuration
│   ├── lib/             # Shared utilities
│   │   ├── api.ts            # API client
│   │   └── config.ts         # Config management
│   └── index.ts         # CLI entry point
├── examples/            # Example files
│   └── content-import-sample.json
└── package.json

Version & Updates

# Check current version
decoupled-cli --version

# Update to latest
npm install -g decoupled-cli@latest

# View changelog
npm view decoupled-cli versions

Current Version: 2.9.5

Recent Changes:

• Added mcp configure --project for project-level .mcp.json with env var support
• Perfect for Claude Code web and team workflows
• Fixed MCP tool schema inconsistencies (delete_space, create_space parameters)
• Fixed Cursor MCP config path (now uses ~/.cursor/mcp.json)
• MCP endpoint moved to https://mcp.decoupled.io (Contabo proxy for better AI compatibility)
• Automatically detects production vs local (localhost uses /api/mcp)
• Updated MCP server name to "Decoupled.io" (Cursor) and "decoupled-io" (Claude Code)
• Switched to HTTP-only transport for MCP (removed SSE/stdio)
• Updated MCP protocol version to 2024-11-05
• Simplified authentication flow to two-step process (login + token)
• Added npx usage examples throughout documentation

Getting Help

# General help
decoupled-cli --help

# Command-specific help
decoupled-cli [command] --help

# Examples
decoupled-cli spaces --help
decoupled-cli mcp configure --help

Additional Resources:

• Documentation: Check the main repository docs
• Issues: Report bugs on GitHub
• Support: Contact through the dashboard

License

MIT

Made with ❤️ by the Decoupled.io team