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
• 🚀 Quick Start - AI-powered space creation with generated content
• 📥 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

Quick Start Example:

# Authenticate and configure MCP in two commands
npx decoupled-cli@latest auth login
npx decoupled-cli@latest mcp configure --ide claude-code

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>]

# 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

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"

Quick Start (AI-Powered) ⚡

Create a fully-functional Drupal space with AI-generated content types and sample data from a single prompt. Perfect for prototyping, demos, and getting started quickly.

# One-shot space creation with AI-generated content
decoupled-cli spaces quick-start "blog about coffee"

# Preview generated content without creating space
decoupled-cli spaces quick-start "e-commerce store" --preview

# Custom space configuration
decoupled-cli spaces quick-start "portfolio site" \
  --name "my-portfolio" \
  --type premium \
  --environment sfo1

# Add AI-generated content to existing space
decoupled-cli spaces quick-start "add products" --space-id 123

How it works:

1. 🤖 AI generates content type schema and sample data from your prompt
2. 🚀 Creates a new space (or uses existing with --space-id)
3. ⏳ Waits for the space to be ready
4. 📥 Imports the AI-generated content
5. 🎉 Provides GraphQL endpoint and next steps

Example output:

🤖 Generating content with AI...
✅ Content generated successfully
   Content types: 1 (post)
   Sample nodes: 3
   Tokens used: 542

🚀 Creating new space...
✅ Space created: blog-about-coffee (ID: 123)

⏳ Waiting for space to be ready............✅

📥 Importing content to space...
✅ Content imported successfully!

🎉 Quick Start Complete!
Space: blog-about-coffee (ID: 123)
URL: https://abc123.decoupled.website
GraphQL: https://abc123.decoupled.website/graphql

📋 Next Steps:
1. Visit your space: https://abc123.decoupled.website
2. Login to Drupal admin: decoupled-cli spaces login 123
3. Create Next.js frontend: npx create-next-app...

Options:

• --preview - See generated JSON without creating space
• --name <name> - Custom space name (auto-generated from prompt if not provided)
• --type <type> - Space type: starter, pro, premium (default: starter)
• --environment <env> - Server environment: nyc1, sfo1, lon1, etc. (default: nyc1)
• --space-id <id> - Use existing space instead of creating new one

Note: This feature uses centrally-managed AI (Groq) - no API keys needed! Requires PAT authentication.

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

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

Recent Changes:

• NEW: 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
• Improved MCP health check compatibility

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