CLI Reference

Command-line interface for development, deployment, testing, and operations

DeepChain CLI Reference

The DeepChain CLI is your command-line tool for everything: development, testing, deployment, and operations. Whether you're building locally or managing production, the CLI handles it all.

Installation

Choose the method that works best for you:

Using npm (if you have Node.js)

npm install -g deepchain-cli
deepchain version  # Verify it works

Using Homebrew (macOS/Linux)

brew tap deepchain/tap
brew install deepchain
deepchain version

Direct Download (works everywhere)

curl -fsSL https://deepchain.dev/install.sh | bash

# Or specify a version
curl -fsSL https://deepchain.dev/install.sh | bash -s -- --version 1.0.0

Build from Source

git clone https://github.com/deepchain/deepchain.git
cd deepchain
# The ./deepchain script is ready to use immediately

Your First 5 Minutes

Get up and running quickly:

# 1. Get the source code
git clone https://github.com/deepchain/deepchain.git
cd deepchain

# 2. Initialize (answers a few setup questions)
./deepchain init

# 3. Install dependencies
./deepchain dev setup

# 4. Start everything locally
./deepchain deploy

# 5. Check it's working
./deepchain status

Done! Your local DeepChain is now running at http://localhost:3000.

Tip: Run ./deepchain help anytime to see all available commands.

Common Workflows

Here's how to do typical tasks:

Starting your day (local development)

# Start everything
./deepchain deploy

# Watch for file changes
./deepchain dev watch frontend

# In another terminal, see what's happening
./deepchain logs -f

Creating a custom node

# Generate boilerplate for a new node
./deepchain sdk new-node payment

# Build and register it
./deepchain update-nodes

# Test it
./deepchain test nodes

Deploying to production

# Switch to production config
./deepchain project switch production

# Create a backup first
./deepchain db backup

# Deploy
./deepchain deploy

# Monitor closely
./deepchain monitor --rollback-on-fail

Troubleshooting when things break

# See what's failing
./deepchain status
./deepchain diagnose

# Fix common issues
./deepchain fix rabbitmq
./deepchain fix nginx

# Check logs
./deepchain logs api --tail 50

All Commands

Setup & Initialization

Initialize a new DeepChain project

./deepchain init

Answer the prompts:

  • Project name: What to call your workspace (e.g., "my-company")
  • Environment: Development (local) or Production (cloud)
  • GCP config (if production): Your Google Cloud project details

This creates:

  • .deepchain/projects/<name>/ — your project's configuration
  • .env — secrets and API keys (keep this safe, don't commit it)

Build Docker images

# Build everything (interactive checklist)
./deepchain build

# Build just one service
./deepchain build api
./deepchain build worker
./deepchain build frontend

# Force a full rebuild (ignore cache)
NO_CACHE=true ./deepchain build

The CLI auto-detects your computer (ARM64 for Mac M1/M2, AMD64 for most others).

Project Management

Switch between your dev, staging, and production environments easily.

List all your projects

./deepchain project list

Output:

Available projects:
  * development    (currently active)
    staging
    production

Switch to a different environment

# Work on staging
./deepchain project switch staging

# Now all commands use staging config
./deepchain deploy   # Deploys to staging
./deepchain logs     # Shows staging logs

Create a new project

./deepchain project create my-feature-env

See project details

# Show current project config
./deepchain project info

# Show specific project config
./deepchain project info production

Tip: Always verify which project you're using before deploying! The active project is shown with * in project list.

Development Commands

Run tests

# Test everything
./deepchain test

# Test a specific package
./deepchain test nodes
./deepchain test frontend

# Include code coverage report
./deepchain test --coverage

Check code style

# Lint all code
./deepchain lint

# Lint specific package
./deepchain lint api_server

# Auto-fix style issues
./deepchain lint --fix

Format code

# Format everything
./deepchain format

# Format specific package
./deepchain format shared_models

# Just check (don't modify) — useful for CI
./deepchain format --check

Generate and view documentation

# Build HTML API docs
./deepchain docs generate

# Check docs are complete
./deepchain docs validate

# View locally (opens browser)
./deepchain docs serve          # Default: port 8000
./deepchain docs serve 9000     # Custom port

Development setup and cleanup

# Install all dependencies
./deepchain dev setup

# Remove build artifacts and caches
./deepchain dev clean

# Auto-rebuild when you change code (live reload)
./deepchain dev watch           # Watches frontend (default)
./deepchain dev watch nodes     # Watches SDK packages

Tip: Run ./deepchain dev watch in one terminal while editing code in another for fast feedback.

Workflow Management

List your workflows

./deepchain workflow list

Shows all workflows with their IDs and status.

Run a workflow locally

# Run without inputs
./deepchain workflow run wf_abc123

# Pass data as JSON file
./deepchain workflow run wf_abc123 input.json

# Example input.json:
# {
#   "orderId": "ORDER-12345",
#   "customerEmail": "john@example.com"
# }

Export a workflow

Backup a workflow to JSON (useful for version control):

# Export to stdout
./deepchain workflow export wf_abc123

# Save to file
./deepchain workflow export wf_abc123 my-workflow.json

Import a workflow

Create a workflow from JSON:

./deepchain workflow import my-workflow.json

Validate workflow definition

Check if your workflow JSON is valid before importing:

./deepchain workflow validate my-workflow.json

Returns either ✓ Valid or lists what's wrong.

SDK & Custom Node Development

Create a new custom node

Generate boilerplate code for a custom node:

./deepchain sdk new-node payment
./deepchain sdk new-node webhook_trigger

This creates:

  • nodes/lib/nodes/payment_node.dart — your business logic
  • frontend/lib/src/widgets/nodes/node_uis/payment_node_ui.dart — how it looks in the UI

Then edit those files to implement your logic.

List all available nodes

See what nodes exist and their categories:

./deepchain sdk list-nodes

Output:

Built-in Nodes:
  [integration] HTTP Request
  [data] JSON Parse
  [communication] Send Email
  ...

Validate your SDK code

Check that your SDK packages are set up correctly:

./deepchain sdk validate

Register your new node

After creating a custom node, register it for use:

./deepchain update-nodes

This updates:

  • Backend node registry
  • Frontend UI registry
  • Exports

Now your node appears in the workflow builder UI.

Tip: Run ./deepchain test nodes after creating a node to make sure it works.

Deployment

Deploy everything

./deepchain deploy

For local development: Starts Docker containers For production: Builds, pushes to cloud, and deploys

Caution: On production, this affects live users. Test in development first.

Update to the latest code

./deepchain update

This automatically:

  • Backs up your database first
  • Builds new images
  • Replaces running containers
  • Verifies everything is healthy

Restart services

# Restart everything
./deepchain restart

# Restart a specific service
./deepchain restart api
./deepchain restart rabbitmq

The CLI handles dependencies (e.g., restarting RabbitMQ also restarts dependent services).

Stop everything

./deepchain teardown

This stops all containers. Use ./deepchain deploy to start them again.

Monitoring & Troubleshooting

Check service status

./deepchain status

Shows which services are running (green ✓) or broken (red ✗).

View logs

# Stream all logs (follow mode)
./deepchain logs

# Specific service logs
./deepchain logs api
./deepchain logs worker

# Last 50 lines (don't follow)
./deepchain logs api --tail 50 --no-follow

# Search logs for errors
./deepchain logs | grep -i error

Run health checks

./deepchain health

Tests if each service can receive requests and respond correctly.

Full diagnostics

When something's wrong, run this:

./deepchain diagnose

Comprehensive check of:

  • Is Docker running?
  • Are all services healthy?
  • Are ports available?
  • Disk space?
  • Any recent errors?

Tip: Run this first when something breaks. It usually tells you the fix.

Check message queue health

./deepchain check-queue

Verifies RabbitMQ can accept jobs.

Continuous monitoring

Keep an eye on your system in real-time:

# Just monitor
./deepchain monitor

# Also auto-rollback if something breaks
./deepchain monitor --rollback-on-fail

Runs in the background, checking every 30 seconds and alerting if issues arise.

Database Management

Create a backup

./deepchain db backup

Creates a file: backups/deepchain_20250111_143052.sql

Important: Always backup before major changes or deployments.

Restore from a backup

./deepchain db restore backups/deepchain_20250111_143052.sql

Warning: This overwrites your current database.

Open database shell

Query the database directly:

./deepchain db shell

Then run SQL:

-- List all tables
\dt

-- See a user
SELECT * FROM "User" WHERE email = 'john@example.com';

-- Count workflows
SELECT COUNT(*) FROM workflow;

Run migrations

Update the database schema to the latest version:

./deepchain db migrate

Run this after pulling new code if migrations were added.

AI & LLM Models

Manage local AI models (powered by Ollama).

Check AI status

./deepchain ai status

Shows:

  • Is the Ollama service running?
  • What models are installed and their sizes?
  • Which model is the default?

List installed models

./deepchain ai models

Download a model

# Download (runs on first use)
./deepchain ai pull gemma3:4b
./deepchain ai pull llama3.2:3b    # Smaller, faster
./deepchain ai pull mistral:7b     # Larger, smarter
./deepchain ai pull codellama:7b   # Best for code

Tip: Smaller models (3b) are faster, larger ones (7b+) are smarter. Start small.

Remove a model

./deepchain ai remove mistral:7b

Frees up disk space.

Set the default model

./deepchain ai set-default llama3.2:3b

This model will be used in workflows.

Initialize AI service

# Use the default model (gemma3:4b)
./deepchain ai init

# Or specify a different model
./deepchain ai init llama3.2:3b

Starts Ollama and downloads the model if needed.

SSL/HTTPS Setup

Enable HTTPS on your domain using free Let's Encrypt certificates.

Setup SSL

./deepchain ssl setup

Follow the prompts for:

  • Your domain (e.g., mycompany.deepchain.dev)
  • Your email (for renewal notices)

Takes 2-5 minutes.

Renew certificate

Certificates expire every 90 days. Renew before they expire:

./deepchain ssl renew

Tip: Set a cron job to auto-renew:

0 2 * * * cd /path/to/deepchain && ./deepchain ssl renew

Check certificate status

./deepchain ssl status

Shows expiration date and any issues.

Common Fixes

When things break, try these first:

Fix RabbitMQ connection errors

If you see "failed to connect to RabbitMQ":

./deepchain fix rabbitmq

Restarts the queue service and dependent services.

Fix nginx routing

If API calls return HTML instead of JSON:

./deepchain fix nginx

Reloads the proxy configuration.

Fix file permissions

If you see "permission denied" errors:

./deepchain fix permissions

Sets correct ownership on data directories.

Utilities

Show environment config

./deepchain env

Displays which project and environment you're using.

View current configuration

./deepchain config

Shows settings (sensitive values are masked).

Check CLI version

./deepchain version

Next Steps