Command-line interface for managing Decoupled Drupal spaces, deploying content, and automating workflows. Features content import, space management, and CI/CD integration.
npm install decoupled-cliA 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).
- š 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
``bash`
npm install -g decoupled-cli
You can run the CLI without installing it globally using npx:
`bash`
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 is a simple two-step process:
#### Step 1: Sign in to your dashboard
`bashWith global installation
decoupled-cli 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:
`bash
With global installation
decoupled-cli auth tokenWith 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
$3
If you already have a token, you can enter it directly:
`bash
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:
`bash
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:
`yaml
- 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 fileNote: 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.):
`bash
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.
$3
`bash
View current authentication status
decoupled-cli auth statusSwitch to a different token/instance
decoupled-cli auth login --url https://staging.drupalcloud.comLogout (remove stored credentials)
decoupled-cli auth logoutTest authentication
decoupled-cli auth test
`Note: Token creation and management must be done through the web interface at
/organization/tokens for security reasons.$3
The CLI stores configuration in
~/.decoupled-cli/config.json:`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.
$3
With global installation:
`bash
Log in first (if not already)
decoupled-cli auth loginConfigure MCP for Claude Code
decoupled-cli mcp configure --ide claude-codeOr configure for Cursor
decoupled-cli mcp configure --ide cursor
`With npx (no installation):
`bash
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 URLsYou: "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
`$3
`bash
Configure MCP for an IDE
decoupled-cli mcp configure [--ide ]Create project-level .mcp.json (for Claude Code web/CLI)
decoupled-cli mcp configure --projectShow configuration status
decoupled-cli mcp statusRemove MCP configuration
decoupled-cli mcp removeShow config without writing (for manual setup)
decoupled-cli mcp configure --show-only
`$3
For teams or when using Claude Code on the web, you can create a project-level
.mcp.json that uses environment variables:`bash
npx decoupled-cli@latest mcp configure --project
`This creates a
.mcp.json in your project that references DECOUPLED_API_TOKEN:`json
{
"mcpServers": {
"decoupled-io": {
"type": "http",
"url": "https://mcp.decoupled.io",
"headers": {
"Authorization": "Bearer ${DECOUPLED_API_TOKEN}"
}
}
}
}
`Team members just need to set their token:
`bash
export DECOUPLED_API_TOKEN="dc_tok_your_token_here"
`$3
- 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$3
#### List Spaces
`bash
List all spaces
decoupled-cli spaces listList with additional details
decoupled-cli spaces list --detailedFilter by status
decoupled-cli spaces list --status active
decoupled-cli spaces list --status creating
decoupled-cli spaces list --archivedOutput as JSON
decoupled-cli spaces list --json
`#### Get Space Details
`bash
Get space by ID
decoupled-cli spaces get 123Get space by name
decoupled-cli spaces get my-space-nameOutput as JSON
decoupled-cli spaces get 123 --json
`#### Create Space
`bash
Create a new space
decoupled-cli spaces create "My New Space" --type proAvailable types: starter, pro, premium
With all options
decoupled-cli spaces create "E-commerce Site" \
--type premium \
--description "New e-commerce platform"
`#### Update Space
`bash
Update space name
decoupled-cli spaces update 123 --name "Updated Space Name"Update space type
decoupled-cli spaces update 123 --type premium
`#### Clone Space
`bash
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
`bash
Archive a space
decoupled-cli spaces archive 123Unarchive a space
decoupled-cli spaces unarchive 123
`#### Delete Space
`bash
Delete a space (with confirmation)
decoupled-cli spaces delete 123Force delete without confirmation
decoupled-cli spaces delete 123 --force
`#### Space Operations
`bash
Get Drupal one-time login link
decoupled-cli spaces login 123Check if space is ready
decoupled-cli spaces status 123Retry space creation (if failed)
decoupled-cli spaces retry 123Refresh space usage data
decoupled-cli spaces refresh-usage 123
`$3
#### Import Content
`bash
Import content model and data from JSON file
decoupled-cli content import --file content-import.jsonPreview import without applying changes
decoupled-cli content import --file content-import.json --previewShow example import JSON structure
decoupled-cli content import --example
`Import JSON Format:
`json
{
"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": "Post content here
",
"subtitle": "An introduction"
}
}
]
}
`$3
#### Organization Usage
`bash
Get overall organization usage
decoupled-cli usageGet usage with space breakdown
decoupled-cli usage --breakdownOutput as JSON
decoupled-cli usage --jsonGet usage for specific date range
decoupled-cli usage --from 2025-01-01 --to 2025-01-31
`#### Space-specific Usage
`bash
Get usage for a specific space
decoupled-cli usage space 123Get usage history
decoupled-cli usage space 123 --historyExport usage data
decoupled-cli usage export --format csv --output usage-report.csv
decoupled-cli usage export --format json --output usage-report.json
`$3
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 interfaceThis ensures tokens can only be managed through secure, authenticated web sessions.
$3
#### Organization Info
`bash
Get organization details
decoupled-cli org infoGet organization members
decoupled-cli org membersGet security settings
decoupled-cli org security
`#### User Management
`bash
List organization users
decoupled-cli users listInvite new user
decoupled-cli users invite user@example.com --role developerUpdate user role
decoupled-cli users update 789 --role adminAvailable roles: owner, admin, developer, member
`$3
#### Health Check
`bash
Check API connectivity
decoupled-cli healthVerbose health check
decoupled-cli health --verbose
`#### Configuration
`bash
Show current configuration
decoupled-cli config showSet configuration values
decoupled-cli config set output json
decoupled-cli config set timeout 30Reset configuration to defaults (with confirmation)
decoupled-cli config resetReset configuration to defaults (skip confirmation)
decoupled-cli config reset --confirmAvailable settings:
- output: table, json, yaml
- timeout: API request timeout in seconds
- color: true, false (enable/disable colored output)
`$3
All commands support these global options:
`bash
--profile # 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 # Override default request timeout
`Examples
$3
`bash
Check overall status
decoupled-cli usage && decoupled-cli spaces list --status creatingCreate a development environment
decoupled-cli spaces create "Feature Branch Test" --type starterGet login link for debugging
decoupled-cli spaces login 123Monitor space creation
watch decoupled-cli spaces status 123Export monthly usage report
decoupled-cli usage export --format csv --from 2025-01-01 --to 2025-01-31
`$3
`bash
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
`$3
`bash
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 errorEnvironment 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 outputSecurity
- 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
$3
`bash
Token authentication failed
decoupled-cli auth test
decoupled-cli auth loginAPI connectivity issues
decoupled-cli health --verbosePermission denied
decoupled-cli tokens list # Check your token permissionsTimeout errors
decoupled-cli config set timeout 60
`$3
`bash
Enable debug output
decoupled-cli --verbose spaces listCheck configuration
decoupled-cli config showTest 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 spaceContent Operations:
-
POST /api/spaces/{id}/content-import - Import content model and dataUsage & Monitoring:
-
GET /api/usage - Get usage data
- GET /api/organization - Get organization detailsMCP (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 messagesAuthentication:
- 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
$3
`bash
Clone repository
git clone https://github.com/nextagencyio/decoupled-dashboard.git
cd decoupled-dashboard/cliInstall dependencies
npm installBuild TypeScript
npm run buildRun locally
npm start -- [command]Watch mode for development
npm run dev
`$3
`
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
`bash
Check current version
decoupled-cli --versionUpdate to latest
npm install -g decoupled-cli@latestView 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 documentationGetting Help
`bash
General help
decoupled-cli --helpCommand-specific help
decoupled-cli [command] --helpExamples
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
MIT
---
Made with ā¤ļø by the Decoupled.io team