CLI Reference

Manage your Drupal spaces, deploy content, and automate workflows directly from your terminal with decoupled-cli.

Installation

Run with npx

npx decoupled-cli@latest

Using npx decoupled-cli@latest ensures you always run the latest version without needing a global install.

Authentication

Initial Setup

Before using the CLI, authenticate with your decoupled.io account:

npx decoupled-cli@latest auth login

This will open your browser where you can:

• Sign in to your decoupled.io account
• Create a personal access token
• Copy and paste the token in your terminal

Pro tip: For CI/CD pipelines, set the DECOUPLED_CLI_TOKEN environment variable to skip interactive login.

Token Management

# View authentication status
npx decoupled-cli@latest auth status

# Generate a Personal Access Token
npx decoupled-cli@latest auth token

# Test your token
npx decoupled-cli@latest auth test

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

Space Management

Common Space Operations

# List all spaces
npx decoupled-cli@latest spaces list

# Get space details
npx decoupled-cli@latest spaces get 123

# Create a new space
npx decoupled-cli@latest spaces create "My New Site" --type starter

# Delete a space
npx decoupled-cli@latest spaces delete 123 --force

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

# Get OAuth credentials for .env.local
npx decoupled-cli@latest spaces env 123

# Check space status
npx decoupled-cli@latest spaces status 123

# Set default space for commands
npx decoupled-cli@latest spaces use 123

Space Types

Content Import

Starter Template Workflow (Recommended)

The easiest way to import content is using the starter template. It includes a pre-configured JSON file and automatically detects your OAuth credentials from .env.local.

# Clone the starter template
npx degit nextagencyio/decoupled-starter my-app
cd my-app

# Install dependencies
npm install

# Add your .env.local (copy from Drupal admin)

# Import the starter content - auto-detects OAuth from .env.local
npm run setup-content

The starter includes data/starter-content.json with Homepage, Article, and Page content types plus sample content.

Direct CLI Import

Import content types and sample data directly from JSON files. The CLI auto-detects OAuth credentials from .env.local, or you can specify a space ID.

# Auto-detect from .env.local (recommended)
npx decoupled-cli@latest content import --file data/starter-content.json

# Preview what will be imported
npx decoupled-cli@latest content import --file content.json --preview

# Specify space ID explicitly (for CI/CD or no .env.local)
npx decoupled-cli@latest content import --file content.json --space 123

# Generate example import JSON structure
npx decoupled-cli@latest content import --example > content.json

OAuth Auto-Detection

When your .env.local contains these variables, the CLI imports directly to your Drupal site:

• NEXT_PUBLIC_DRUPAL_BASE_URL
• DRUPAL_CLIENT_ID
• DRUPAL_CLIENT_SECRET

Example Import JSON

{
  "model": [
    {
      "bundle": "homepage",
      "label": "Homepage",
      "fields": [
        { "id": "hero_title", "label": "Hero Title", "type": "string" },
        { "id": "hero_subtitle", "label": "Hero Subtitle", "type": "string" },
        { "id": "features_items", "label": "Features", "type": "paragraph(feature_item)[]" }
      ]
    },
    {
      "bundle": "article",
      "label": "Article",
      "body": true,
      "fields": [
        { "id": "image", "label": "Featured Image", "type": "image" },
        { "id": "tags", "label": "Tags", "type": "term(tags)[]" }
      ]
    },
    {
      "entity": "paragraph",
      "bundle": "feature_item",
      "label": "Feature Item",
      "fields": [
        { "id": "icon", "label": "Icon", "type": "string" },
        { "id": "title", "label": "Title", "type": "string!" },
        { "id": "description", "label": "Description", "type": "text" }
      ]
    }
  ],
  "content": [
    {
      "id": "homepage",
      "type": "node.homepage",
      "path": "/homepage",
      "values": {
        "title": "My Site",
        "hero_title": "Welcome",
        "hero_subtitle": "Build something amazing"
      }
    }
  ]
}

Field Types Reference

Config Import

Import Drupal Configuration

Import Drupal configuration YAML (views, image styles, roles, menus, etc.) directly from JSON files. The CLI auto-detects OAuth credentials from .env.local, or you can specify a space ID.

# Auto-detect from .env.local (recommended)
npx decoupled-cli@latest config-import import --file config.json

# Preview what will be imported
npx decoupled-cli@latest config-import import --file config.json --preview

# Specify space ID explicitly
npx decoupled-cli@latest config-import import --file config.json --space 123

# Show allowed config types
npx decoupled-cli@latest config-import allowed-types

# Generate example config import JSON
npx decoupled-cli@latest config-import example > config.json

Example Config Import JSON

{
  "configs": [
    {
      "name": "image.style.wide",
      "yaml": "langcode: en\nstatus: true\nname: wide\nlabel: Wide\n..."
    },
    {
      "name": "user.role.editor",
      "yaml": "langcode: en\nstatus: true\nid: editor\nlabel: Editor\n..."
    }
  ]
}

Allowed Config Types: You can import views, image styles, menus, content type settings, field configs, display modes, taxonomy vocabularies, blocks, roles, text formats, editor configs, and pathauto patterns. Dangerous configs like core.extension are blocked for safety.

Organization

Organization Commands

# View organization details
npx decoupled-cli@latest org info

Usage Monitoring

Track Resource Usage

Monitor your organization's usage, track space-specific metrics, and export reports.

# Get overall organization usage
npx decoupled-cli@latest usage

# Get usage with space breakdown
npx decoupled-cli@latest usage --breakdown

# Get usage for specific space
npx decoupled-cli@latest usage space 123

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

# Get usage for date range
npx decoupled-cli@latest usage --from 2025-01-01 --to 2025-01-31

CI/CD Integration

GitHub Actions

Automate space provisioning and content deployment with GitHub Actions.

# .github/workflows/provision.yml
name: Provision Preview Environment
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  provision:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install CLI
        run: npx decoupled-cli@latest --version

      - name: Create Space
        env:
          DECOUPLED_CLI_TOKEN: ${{ secrets.DECOUPLED_CLI_TOKEN }}
        run: |
          SPACE_NAME="pr-${{ github.event.pull_request.number }}"
          npx decoupled-cli@latest spaces create "$SPACE_NAME" --type starter

      - name: Import Content
        env:
          DECOUPLED_CLI_TOKEN: ${{ secrets.DECOUPLED_CLI_TOKEN }}
        run: |
          SPACE_ID=$(npx decoupled-cli@latest spaces list --json | jq -r '.spaces[0].id')
          npx decoupled-cli@latest spaces content-import $SPACE_ID --file content.json

Environment Variable Setup

For automated environments, 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.

Global Options

These options can be used with any CLI command:

Configuration

CLI Settings

# Show current configuration
npx decoupled-cli@latest config show

# Set output format
npx decoupled-cli@latest config set output json

# Set request timeout
npx decoupled-cli@latest config set timeout 60

# Reset to defaults
npx decoupled-cli@latest config reset --confirm

MCP Integration

Configure the MCP server for AI-powered Drupal management directly from your IDE. See the full MCP documentation for details.

# Configure MCP for Claude Code CLI
npx decoupled-cli@latest mcp configure --ide claude-code

# Configure MCP for Cursor
npx decoupled-cli@latest mcp configure --ide cursor

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

# Check MCP configuration status
npx decoupled-cli@latest mcp status

# Remove MCP configuration
npx decoupled-cli@latest mcp remove

# Show config without writing
npx decoupled-cli@latest mcp configure --show-only

Real-world Examples

Create Development Environment

# Create starter space
npx decoupled-cli@latest spaces create "Dev Environment" --type starter

# Import content structure
npx decoupled-cli@latest spaces content-import 123 --file content.json

# Get admin login link
npx decoupled-cli@latest spaces login 123

Monitor Space Creation

# Check spaces stuck in 'creating' status
npx decoupled-cli@latest spaces list --status creating --json

# Watch space status in real-time
watch npx decoupled-cli@latest spaces status 123

Generate Monthly Report

# Export monthly usage report
npx decoupled-cli@latest usage export \
  --format csv \
  --from 2025-01-01 \
  --to 2025-01-31 \
  --output january-usage.csv

Troubleshooting

Authentication Issues

If you're having authentication problems:

# Check authentication status
npx decoupled-cli@latest auth test

# Re-authenticate
npx decoupled-cli@latest auth logout
npx decoupled-cli@latest auth login

API Connectivity

Test API connectivity with verbose output:

# Check API health
npx decoupled-cli@latest health --verbose

Debug Mode

Enable verbose logging for detailed debugging:

# Run with verbose output
npx decoupled-cli@latest --verbose spaces list

# Check configuration
npx decoupled-cli@latest config show