// DSHELL CLI REFERENCE

DShell Distributed Shell

Complete command reference for interactive and batch automation across your Dimensigon cluster.

What is DShell?

DShell is the Distributed Shell - a powerful command-line interface for managing your Dimensigon cluster. Use it interactively for ad-hoc operations or in batch mode for automation scripts. DShell features tab completion, syntax highlighting, and translates all commands to REST API requests.

1. Getting Started with DShell

Starting DShell
# Start interactive DShell (default)
$ dshell

# Connect to specific server and port
$ dshell -s server-name -p 20194

# Connect as specific user
$ dshell -s server-name -u admin

# Save credentials for automation
root.dshell> login --save

# Get help on any command
root.dshell> help

# Get specific command help
root.dshell> help software

# Exit DShell
root.dshell> exit

Connection Options

  • -s - Target server hostname/IP
  • -p - API port (default: 20194)
  • -u - Username for authentication
  • --save - Store credentials in keyring

Tab completion enabled in interactive mode. Press TAB to see available commands.

2. Server Management Commands

Server Commands

Query and monitor all servers in your dimension:

  • List all nodes and their status
  • Check network connectivity
  • View node topology and gates
  • Monitor server resources
Server Management
# List all servers in dimension
root.dshell> server list

Name           | Status  | Gates | Catalog Version
prod-1         | ONLINE  | 2     | 1542
prod-2         | ONLINE  | 2     | 1542
staging-1      | ONLINE  | 1     | 1542

# Ping a server (check connectivity)
root.dshell> server ping -n prod-1
SUCCESS: Response time 14ms

# Get detailed server info
root.dshell> server info -n prod-1

3. Software Management

Software Library Management
# Add software to library
root.dshell> software add /path/to/file.tar.gz \
  -name "my-app" -family "apps" \
  -server prod-1

# List all software in library
root.dshell> software list

# Send software to specific node
root.dshell> software send \
  -name "my-app" \
  -dest /opt/applications/ \
  -n prod-2

# Broadcast to all nodes
root.dshell> software send \
  -name "my-app" \
  -dest /opt/applications/ \
  --broadcast

# Delete from library
root.dshell> software delete -name "my-app"

Software Management Benefits

  • Register once, deploy anywhere
  • Works through mesh networking (no direct connectivity needed)
  • Progress tracking for large files
  • Support for archives and individual files
  • Optional server specification

4. Orchestration Management

Orchestration Commands

Define, deploy, and execute distributed workflows:

  • Create orchestrations from JSON
  • Execute on single or multiple nodes
  • Monitor execution progress
  • View execution history and logs
Orchestration Commands
# Create orchestration from file
root.dshell> orch create my-deploy \
  -file ./deploy.json

# List all orchestrations
root.dshell> orch list

# Run orchestration on specific node
root.dshell> orch run -n my-deploy \
  --node prod-1

# Monitor execution
root.dshell> orch execution list -n my-deploy

# View execution details
root.dshell> orch execution info \
  -id exec-12345

# Delete orchestration
root.dshell> orch delete -n my-deploy

5. Vault (Secrets Management)

Vault Commands
# Store a secret in vault
root.dshell> vault set db-password \
  "super$ecure!pass123"

# Retrieve a secret
root.dshell> vault get db-password
super$ecure!pass123

# List all vault entries you have access to
root.dshell> vault list

# Delete a secret
root.dshell> vault delete db-password

# Use vault in orchestrations
# Within JSON code field: {{vault.db-password}}

Vault Security Features

  • Fernet encryption at rest
  • TLS encryption in transit
  • Access control via ACLs
  • Distributed replication
  • Never logged or exposed

6. Lock Management (Distributed Locking)

Distributed Locking

Coordinate critical operations with quorum-based consensus:

  • Acquire locks for critical sections
  • Requires majority node agreement
  • Prevents concurrent operations
  • Auto-release on timeout
Lock Commands
# Acquire distributed lock
root.dshell> manager lock acquire \
  --scope db-migration
Lock acquired. Holder: dshell-session-001

# Check lock status
root.dshell> manager lock status \
  --scope db-migration
LOCKED by dshell-session-001 (4/7 nodes)

# Release the lock
root.dshell> manager lock release \
  --scope db-migration
Lock released

7. Batch Mode (Scripting)

Batch Mode Execution
# Execute single command from shell
$ dshell server list

# Use in shell scripts
$ cat > deploy.sh <<'EOF'
#!/bin/bash
# Check cluster health
dshell manager status

# Run deployment
dshell orch run -n deploy-v2 --node prod-1

# Monitor
dshell orch execution list -n deploy-v2
EOF

# Execute script
$ bash deploy.sh

# With saved credentials (no interactivity)
$ dshell -s prod-1 vault get db-password

Batch Mode Advantages

  • No interactive prompt required
  • Perfect for cron jobs and CI/CD
  • Exit codes for error handling
  • Scriptable with bash/python
  • Save credentials for automation

8. User & Authentication Management

Authentication & Authorization

Manage users, groups, and access permissions:

  • Create users and assign groups
  • JWT-based authentication
  • Group-based ACLs
  • Credential storage in keyring
User Management
# Login and save credentials
root.dshell> login --save
Username: alice
Password: ••••••••
Authenticated successfully

# List users
root.dshell> user list

# List groups
root.dshell> group list

# View your current permissions
root.dshell> whoami

9. Advanced: Subscription & Monitoring

Subscription Commands
# Subscribe to server status updates
root.dshell> subscribe server-status

# Subscribe to log federation
root.dshell> subscribe logfed

# View subscriptions
root.dshell> subscription list

# Unsubscribe from updates
root.dshell> unsubscribe logfed

# Monitor cluster in real-time
root.dshell> manager status --watch

Monitoring & Events

  • Real-time status updates
  • Log federation monitoring
  • Execution tracking
  • Watch mode for continuous updates

10. Quick Command Reference Table

Command Summary
# Server Commands
server list, server info, server ping

# Software Management
software add, software list, software send, software delete

# Orchestrations
orch create, orch list, orch run, orch delete
orch execution list, orch execution info

# Vault (Secrets)
vault set, vault get, vault list, vault delete

# Locking
manager lock acquire, manager lock status, manager lock release

# Authentication
login, logout, whoami

# Help & Info
help, help <command>, exit

Help & Documentation

  • help - Show all commands
  • help <cmd> - Show command details
  • Tab completion for all commands
  • Flag help: <cmd> --help
⚡

Fast & Responsive

Tab completion and syntax highlighting for quick command entry.

🔐

Secure by Default

JWT authentication, credential storage, and ACL-based access control.

📜

Full API Access

Every REST API capability accessible from DShell commands.

🤖

Automation Ready

Batch mode for scripts, cron jobs, and CI/CD pipelines.

Core Concepts & Use Cases Installation Tutorial