Depictio CLI Usage¶

Note about the CLI

The depictio-cli is a command line interface that allows you to interact with the Depictio backend. It is used to register projects information including workflow files metadata. The depictio-cli is currently in development and is not yet ready for production use.

Installation¶

See the installation guide for instructions on how to install the depictio-cli.

Quick Reference¶

Command	Description	Access Level
`version`	Show CLI version	All users
`run`	Execute complete workflow	All users
`config show-cli-config`	Display CLI configuration	All users
`config check-s3-storage`	Validate S3 storage setup	All users
`config check-server-accessibility`	Test server connection	All users
`config validate-project-config`	Validate project configuration	All users
`config sync-project-config-to-server`	Sync project config to server	All users
`data scan`	Scan project files	All users
`data process`	Process data collections	All users
`backup backup`	Create system backup	Admin only
`backup restore`	Restore from backup	Admin only
`backup list-backups`	List available backups	Admin only

Global Options¶

Option	Short	Type	Default	Description
`--verbose`	`-v`	`boolean`	`false`	Enable verbose logging
`--verbose-level`	`-vl`	`string`	`"INFO"`	Set verbose logging level

🚀 Commands¶

🏃 Run Command¶

🎬 🖥️ `depictio-cli run` command example

Execute the complete Depictio workflow: validate → sync → scan → process

depictio-cli run [OPTIONS]

Quick Start:

depictio-cli run --project-config-path ./config.yaml

Pipeline Steps:

✅ Check server accessibility
✅ Check S3 storage configuration
✅ Validate project configuration
✅ Sync project configuration to server
✅ Scan data files
✅ Process data collections

📋 Basic Configuration

Parameter	Type	Default	Description
`--CLI-config-path`	`string`	`~/.depictio/CLI.yaml`	CLI configuration file path
`--project-config-path`	`string`	`""`	Pipeline configuration file path
`--workflow-name`	`string`	`null`	Specific workflow to process
`--data-collection-tag`	`string`	`null`	Data collection tag to process

⚙️ Flow Control Options

Parameter	Type	Default	Description
`--skip-server-check`	`boolean`	`false`	Skip server accessibility check
`--skip-s3-check`	`boolean`	`false`	Skip S3 storage validation
`--skip-sync`	`boolean`	`false`	Skip config sync to server
`--skip-scan`	`boolean`	`false`	Skip data scanning step
`--skip-process`	`boolean`	`false`	Skip data processing step

🔄 Sync & Scan Options

Parameter	Type	Default	Description
`--update-config`	`boolean`	`false`	Update project configuration on server
`--rescan-folders`	`boolean`	`false`	Reprocess all runs for data collection
`--sync-files`	`boolean`	`false`	Update files for data collection
`--overwrite`	`boolean`	`false`	Overwrite workflow if it already exists

🖥️ Output & Control

Parameter	Type	Default	Description
`--rich-tables`	`boolean`	`false`	Show detailed execution summary
`--continue-on-error`	`boolean`	`false`	Continue execution on step failure
`--dry-run`	`boolean`	`false`	Show execution plan without running

Examples:

Basic Usage

# Complete workflow execution
depictio-cli run --project-config-path ./config.yaml

Development

# With detailed output and error handling
depictio-cli run \
  --project-config-path ./config.yaml \
  --continue-on-error \
  --rich-tables

Dry Run

# Preview execution without running
depictio-cli run \
  --project-config-path ./config.yaml \
  --dry-run

Skip Steps

# Skip server checks for faster execution
depictio-cli run \
  --project-config-path ./config.yaml \
  --skip-server-check \
  --skip-s3-check

📋 Config Commands¶

Command Group: depictio-cli config

All commands in this section are part of the config command family. Use them to manage Depictio configurations and validate connections.

Manage Depictio configurations and validate connections.

`config show-cli-config`¶

Display the current CLI configuration.

depictio-cli config show-cli-config [OPTIONS]

Parameter	Type	Default	Description
`--CLI-config-path`	`string`	`~/.depictio/CLI.yaml`	CLI configuration file path

depictio-cli config show-cli-config

`config check-s3-storage`¶

Validate S3 storage configuration.

depictio-cli config check-s3-storage [OPTIONS]

Parameter	Type	Default	Description
`--CLI-config-path`	`string`	`~/.depictio/CLI.yaml`	CLI configuration file path

depictio-cli config check-s3-storage

`config check-server-accessibility`¶

Test connection to Depictio server.

depictio-cli config check-server-accessibility [OPTIONS]

Parameter	Type	Default	Description
`--CLI-config-path`	`string`	`~/.depictio/CLI.yaml`	CLI configuration file path

depictio-cli config check-server-accessibility

`config show-depictio-project-metadata-on-server`¶

Display metadata for registered projects.

depictio-cli config show-depictio-project-metadata-on-server [OPTIONS]

Parameter	Type	Default	Description
`--CLI-config-path`	`string`	`~/.depictio/CLI.yaml`	CLI configuration file path
`--project-name`	`string`	`""`	Specific project name

depictio-cli config show-depictio-project-metadata-on-server --project-name my-project

`config validate-project-config`¶

Validate project configuration file.

depictio-cli config validate-project-config [OPTIONS]

Parameter	Type	Default	Description
`--CLI-config-path`	`string`	`~/.depictio/CLI.yaml`	CLI configuration file path
`--project-config-path`	`string`	`""`	Pipeline configuration file path

depictio-cli config validate-project-config --project-config-path ./config.yaml

`config sync-project-config-to-server`¶

Sync project configuration to server.

depictio-cli config sync-project-config-to-server [OPTIONS]

Parameter	Type	Default	Description
`--CLI-config-path`	`string`	`~/.depictio/CLI.yaml`	CLI configuration file path
`--project-config-path`	`string`	`""`	Pipeline configuration file path
`--update`	`boolean`	`false`	Update existing project configuration

depictio-cli config sync-project-config-to-server --project-config-path ./config.yaml --update

📊 Data Commands¶

Command Group: depictio-cli data

All commands in this section are part of the data command family. Use them to manage data scanning and processing operations.

Manage data scanning and processing operations.

`data scan`¶

Scan project files for data collections.

depictio-cli data scan [OPTIONS]

Parameter	Type	Default	Description
`--CLI-config-path`	`string`	`~/.depictio/CLI.yaml`	CLI configuration file path
`--project-config-path`	`string`	`""`	Pipeline configuration file path
`--workflow-name`	`string`	`null`	Specific workflow to scan
`--data-collection-tag`	`string`	`null`	Data collection tag to scan
`--rescan-folders`	`boolean`	`false`	Reprocess all runs for data collection
`--sync-files`	`boolean`	`false`	Update files for data collection

depictio-cli data scan --project-config-path ./config.yaml --workflow-name my-workflow

`data process`¶

Process data collections for workflow execution.

depictio-cli data process [OPTIONS]

Parameter	Type	Default	Description
`--CLI-config-path`	`string`	`~/.depictio/CLI.yaml`	CLI configuration file path
`--project-config-path`	`string`	`""`	Pipeline configuration file path
`--overwrite`	`boolean`	`false`	Overwrite existing workflow

depictio-cli data process --project-config-path ./config.yaml --overwrite

💾 Backup Commands¶

Command Group: depictio-cli backup

All commands in this section are part of the backup command family. Use them to backup and restore system data and configurations.

Backup and restore system data and configurations.

Admin Access Required

Backup and restore commands require administrator privileges. Only users with admin access can perform backup and restore operations. Ensure your CLI configuration includes admin credentials.

`backup backup`¶

Create a backup of database and S3 storage data.

depictio-cli backup backup [OPTIONS]

Parameter	Type	Default	Description
`--CLI-config-path`	`string`	`~/.depictio/CLI.yaml`	CLI configuration file path
`--backup-name`	`string`	`timestamp`	Name for the backup
`--include-s3`	`boolean`	`true`	Include S3 storage data in backup
`--include-db`	`boolean`	`true`	Include database data in backup
`--output-path`	`string`	`./backups`	Path where backup files are stored

depictio-cli backup backup --backup-name production-backup --output-path ./backups

`backup restore`¶

Restore data from a previously created backup.

depictio-cli backup restore [OPTIONS]

Parameter	Type	Default	Description
`--CLI-config-path`	`string`	`~/.depictio/CLI.yaml`	CLI configuration file path
`--backup-path`	`string`	required	Path to backup file or directory
`--restore-s3`	`boolean`	`true`	Restore S3 storage data
`--restore-db`	`boolean`	`true`	Restore database data
`--force`	`boolean`	`false`	Force restore without confirmation

depictio-cli backup restore --backup-path ./backups/production-backup --force

`backup list-backups`¶

List all available backups.

depictio-cli backup list-backups [OPTIONS]

Parameter	Type	Default	Description
`--backup-path`	`string`	`./backups`	Path to backup directory

depictio-cli backup list-backups --backup-path ./backups

🛠️ Common Use Cases¶

🚀 Quick Start¶

Complete Setup

# 1. Validate your project configuration
depictio-cli config validate-project-config --project-config-path ./config.yaml

# 2. Run the complete workflow
depictio-cli run --project-config-path ./config.yaml

Step by Step

# 1. Check system status
depictio-cli config check-server-accessibility
depictio-cli config check-s3-storage

# 2. Validate and sync configuration
depictio-cli config validate-project-config --project-config-path ./config.yaml
depictio-cli config sync-project-config-to-server --project-config-path ./config.yaml

# 3. Scan and process data
depictio-cli data scan --project-config-path ./config.yaml
depictio-cli data process --project-config-path ./config.yaml

🔧 Development Workflow¶

Testing Changes

# Preview changes without execution
depictio-cli run --project-config-path ./config.yaml --dry-run

# Test with specific workflow
depictio-cli run --project-config-path ./config.yaml --workflow-name test-workflow

Debugging

# Enable verbose logging
depictio-cli run --project-config-path ./config.yaml --verbose --continue-on-error

# Skip problematic steps
depictio-cli run --project-config-path ./config.yaml --skip-server-check --skip-s3-check

💾 Backup Operations¶

Admin Access Required

All backup operations require administrator privileges.

Create Backup

# Create timestamped backup
depictio-cli backup backup --backup-name "backup-$(date +%Y%m%d-%H%M%S)"

# Custom backup location
depictio-cli backup backup --backup-name production-backup --output-path /secure/backups

Restore Backup

# List available backups
depictio-cli backup list-backups --backup-path /secure/backups

# Restore specific backup
depictio-cli backup restore --backup-path /secure/backups/production-backup --force

📊 Data Management¶

Rescan Data

# Rescan all folders
depictio-cli data scan --project-config-path ./config.yaml --rescan-folders

# Sync file updates
depictio-cli data scan --project-config-path ./config.yaml --sync-files

Process Updates

# Overwrite existing workflow
depictio-cli data process --project-config-path ./config.yaml --overwrite

# Update and reprocess
depictio-cli run --project-config-path ./config.yaml --update-config --overwrite

🔧 Error Handling¶

Exit Codes¶

Code	Description	Solution
`0`	Success	Command completed successfully
`1`	Configuration error	Check configuration file paths and syntax
`2`	Server connection failed	Verify server URL and network connectivity
`3`	S3 storage error	Validate S3 credentials and bucket configuration
`4`	Data processing failed	Check data file permissions and formats

Common Issues¶

Connection Problems

Error: "Server not accessible"

Solutions:

# Check server accessibility
depictio-cli config check-server-accessibility

# Verify CLI configuration
depictio-cli config show-cli-config

Configuration Errors

Error: "Project config validation failed"

Solutions:

# Validate configuration with verbose output
depictio-cli config validate-project-config --project-config-path ./config.yaml --verbose

# Check configuration examples
# See: minimal_config.md and full_reference_config.md

Permission Issues

Error: "Admin access required"

Solutions: - Ensure you're logged in with admin credentials - Check CLI configuration includes admin access tokens - Contact system administrator for proper permissions

Troubleshooting Steps¶

1. Check Prerequisites:

Depictio server is running and accessible
CLI configuration file exists (~/.depictio/CLI.yaml)
Project configuration file is valid YAML
Proper permissions for file access

2. Enable Verbose Logging:

depictio-cli [command] --verbose --verbose-level DEBUG

3. Test Components Individually:

depictio-cli config check-server-accessibility
depictio-cli config check-s3-storage
depictio-cli config validate-project-config --project-config-path ./config.yaml

4. Use Dry Run Mode:

depictio-cli run --project-config-path ./config.yaml --dry-run

Depictio CLI Usage¶

📚 Table of Contents¶

Installation¶

Quick Reference¶

Global Options¶

🚀 Commands¶

🏃 Run Command¶

📋 Config Commands¶

config show-cli-config¶

config check-s3-storage¶

config check-server-accessibility¶

config show-depictio-project-metadata-on-server¶

config validate-project-config¶

config sync-project-config-to-server¶