// DSHELL CLI REFERENCE

DShell Distributed Shell

Tested syntax baseline: Dimensigon 0.3.5 on Python 3.9. 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
# Documentation baseline: Dimensigon 0.3.5; examples use a disposable lab.
$ dshell
$ dshell -s LAB_NODE -p 20194
$ dshell -s LAB_NODE -u alice
# Sign in interactively; --save stores a token in the local DShell config.
# Avoid --save on shared machines. The password prompt is not a command argument.
root.dshell> login alice
root.dshell> --help
root.dshell> software --help
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 Observation 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
# Membership and observed status are separate.
root.dshell> server list --detail
root.dshell> ping LAB_NODE
root.dshell> server list --name LAB_NODE --detail
root.dshell> status LAB_NODE --detail

3. Software Management

Software Library Management
# Use a harmless script from your disposable lab.
root.dshell> software add hello-script 1 /tmp/my-script.sh --family demos
root.dshell> software list --name hello-script --detail
# Substitute the returned software UUID and disposable destination UUIDs.
root.dshell> software send SOFTWARE_ID LAB_NODE_ID --dest_path /tmp/ --foreground
root.dshell> software send SOFTWARE_ID LAB_NODE_2_ID --dest_path /tmp/ --foreground
root.dshell> software delete SOFTWARE_ID

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
# Download examples/hello-world.json from the tutorial before importing.
# Interactive import differs from batch `dshell orch create FILE`.
root.dshell> orch load examples/hello-world.json
root.dshell> orch list --name hello-world --detail
root.dshell> orch run ORCHESTRATION_ID all=LAB_NODE
root.dshell> exec list --orch ORCHESTRATION_ID --detail
root.dshell> exec list --id EXECUTION_ID --detail
# Create a new version using the supported copy workflow.
root.dshell> orch copy ORCHESTRATION_ID

5. Vault (Secrets Management)

Vault Commands
# Interactive vault commands; use only synthetic values in this lab.
root.dshell> vault write demo_message 'Hello from the lab' --scope global
root.dshell> vault read demo_message --scope global
root.dshell> vault list --scope global
root.dshell> vault delete demo_message --scope global
# In JSON code, reference {{vault.demo_message}}.
# Vault is an interactive resource in this CLI; it has no batch entrypoint.

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:

  • Inspect the product's scoped locks
  • Requires majority node agreement
  • Prevents concurrent operations
  • Use manual unlock only for approved lab recovery
Lock Commands
# Inspect scoped product locks. Ordinary orchestration handles its own locks.
root.dshell> manager locker show LAB_NODE
# Recovery only in a disposable lab after confirming no execution is active.
root.dshell> manager locker unlock ORCHESTRATION LAB_NODE
root.dshell> manager locker show LAB_NODE

7. Batch Mode (Scripting)

Batch Mode Execution
# Batch commands use their own supported parser.
$ dshell server list --detail
$ dshell status LAB_NODE --detail
$ dshell orch create examples/hello-world.json
$ dshell orch list --name hello-world --detail
$ dshell orch run ORCHESTRATION_ID --target all=LAB_NODE
$ dshell exec list --orch ORCHESTRATION_ID --detail
# Pass IDs and node names explicitly to scripts; never hardcode administrator tokens.

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

Authenticate with the account and scopes granted by your lab administrator:

  • User and group administration uses the receiving product management interface
  • JWT-based authentication
  • Group-based ACLs
  • Optional token storage in a local configuration file
User Management
# Sign in as the account supplied by your lab administrator.
root.dshell> login alice
root.dshell> env get SERVER
root.dshell> vault list --scopes
# User/group administration belongs to the receiving product's management API.
# These DShell parsers provide login and resource operations, not user/group CRUD.
# Tokens saved by login --save are local configuration data, not a system keyring.

9. Advanced: Subscription & Monitoring

Subscription Commands
# Monitor only synthetic lab logs.
root.dshell> status LAB_NODE --detail
root.dshell> logfed subscribe log LAB_NODE /tmp/dm-training.log LAB_COLLECTOR --mode REPO_ROOT
root.dshell> logfed list
root.dshell> logfed unsubscribe LOG_ID
root.dshell> exec list --orch ORCHESTRATION_ID --detail

Monitoring & Events

  • Real-time status updates
  • Log federation monitoring
  • Execution tracking
  • Repeat status observations when needed

10. Quick Command Reference Table

Command Summary
# Interactive server status: server list, ping, status
# Software: software add NAME VERSION FILE; software list; software send UUID NODE_UUID
# Workflow import: orch load FILE (interactive); dshell orch create FILE (batch)
# Run: orch run UUID all=NODE (interactive); dshell orch run UUID --target all=NODE (batch)
# Results: exec list --orch UUID --detail
# Vault: vault write, vault read, vault list, vault delete (interactive)
# Locks: manager locker show; manager locker unlock (lab recovery only)
# Authentication: login USER; exit
# Help: --help; software --help

Help & Documentation

  • help - Show all commands
  • software --help - Show command details
  • Tab completion for all commands
  • Flag help: software --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