CLI Reference

Overview

The Test Orchestration Command-Line Interface (CLI) enables you to create, manage, and execute workflows programmatically. It's ideal for automation, CI/CD integration, and scripting.

💻 Command Line Power

CLI capabilities:

Create and manage projects
Define and execute workflows
Configure execution settings
Retrieve results and reports
Automate common tasks
Integrate with CI/CD systems

Installation

macOS

brew install test-orchestration

Linux

# Ubuntu/Debian
sudo apt-get install test-orchestration

# RedHat/CentOS
sudo yum install test-orchestration

# From source
curl -fsSL https://download.test-orchestration.com/install.sh | bash

Windows

# Using Chocolatey
choco install test-orchestration

# Using Windows Package Manager
winget install TestOrchestration.CLI

# Manual download
# Download from https://downloads.test-orchestration.com/windows

Verify Installation

to-cli --version
# Output: Test Orchestration CLI v2.4.0

Basic Commands

Help and Information

# Show help
to-cli --help
to-cli -h

# Show version
to-cli --version
to-cli -v

# Get help for specific command
to-cli workflow --help
to-cli create workflow --help

Project Commands

# List all projects
to-cli project list

# Get project details
to-cli project info PROJECT_ID

# Create new project
to-cli project create --name "My Project"

# Update project
to-cli project update PROJECT_ID --name "Updated Name"

# Delete project
to-cli project delete PROJECT_ID

Workflow Commands

# List workflows in project
to-cli workflow list --project PROJECT_ID

# Get workflow details
to-cli workflow info WORKFLOW_ID

# Create workflow
to-cli workflow create --project PROJECT_ID --name "Test Flow"

# Update workflow
to-cli workflow update WORKFLOW_ID --name "Updated Flow"

# Delete workflow
to-cli workflow delete WORKFLOW_ID

# Execute workflow
to-cli workflow execute WORKFLOW_ID

# Get workflow status
to-cli workflow status EXECUTION_ID

Authentication

API Token

# Set API token (one-time)
to-cli auth set-token YOUR_API_TOKEN

# Or use environment variable
export TO_API_TOKEN=your_token_here
to-cli project list

# Verify authentication
to-cli auth verify

# Interactive login
to-cli login

# With username/password
to-cli login --username [email protected] --password yourpassword

# Login to specific environment
to-cli login --environment production

Logout

to-cli logout

Workflow Execution

Execute Workflow

# Basic execution
to-cli workflow execute WORKFLOW_ID

# With environment variables
to-cli workflow execute WORKFLOW_ID \
  --env ENV_VAR1=value1 \
  --env ENV_VAR2=value2

# With input parameters
to-cli workflow execute WORKFLOW_ID \
  --input "param1=value1" \
  --input "param2=value2"

# With timeout (in seconds)
to-cli workflow execute WORKFLOW_ID --timeout 3600

# Get execution ID
EXEC_ID=$(to-cli workflow execute WORKFLOW_ID --output json | jq -r '.execution_id')

Monitor Execution

# Check execution status
to-cli workflow status EXECUTION_ID

# Watch execution in real-time
to-cli workflow watch EXECUTION_ID

# Get execution details
to-cli workflow info EXECUTION_ID --details

# List recent executions
to-cli workflow executions WORKFLOW_ID --limit 10

# Get specific execution logs
to-cli workflow logs EXECUTION_ID

Cancel Execution

# Cancel running execution
to-cli workflow cancel EXECUTION_ID

# Force cancel
to-cli workflow cancel EXECUTION_ID --force

Configuration

Configuration File

# Show current configuration
to-cli config show

# Set configuration value
to-cli config set key value

# Common settings
to-cli config set api_url https://api.test-orchestration.com
to-cli config set default_project PROJECT_ID
to-cli config set timeout 3600
to-cli config set output_format json

Environment Variables

# API Configuration
export TO_API_URL=https://api.test-orchestration.com
export TO_API_TOKEN=your_token_here

# Proxy Configuration
export TO_PROXY_HOST=proxy.company.com
export TO_PROXY_PORT=8080
export TO_PROXY_USER=username
export TO_PROXY_PASSWORD=password

# Output Configuration
export TO_OUTPUT_FORMAT=json
export TO_VERBOSE=true
export TO_DEBUG=true

# Workspace Configuration
export TO_WORKSPACE=/path/to/workspace
export TO_PROJECT_ID=default_project_id

Configuration File Locations

# macOS/Linux
~/.config/test-orchestration/config.yml
~/.test-orchestration/credentials

# Windows
%APPDATA%\TestOrchestration\config.yml
%APPDATA%\TestOrchestration\credentials

Output Formats

Default (Table)

to-cli workflow list

Output:

ID              NAME           STATUS    LAST_RUN
wf_001          Login Test     Active    2024-01-15
wf_002          Checkout Flow  Active    2024-01-14
wf_003          Search Test    Inactive  2024-01-10

JSON Output

to-cli workflow list --output json
# or
to-cli workflow list -o json

Output:

[
  {
    "id": "wf_001",
    "name": "Login Test",
    "status": "active"
  }
]

CSV Output

to-cli workflow list --output csv

Output:

ID,NAME,STATUS,LAST_RUN
wf_001,Login Test,Active,2024-01-15

YAML Output

to-cli workflow list --output yaml

Data Import/Export

Export Workflow

# Export to JSON
to-cli workflow export WORKFLOW_ID --format json > workflow.json

# Export to YAML
to-cli workflow export WORKFLOW_ID --format yaml > workflow.yaml

# Export with execution history
to-cli workflow export WORKFLOW_ID --include-history > workflow_full.json

Import Workflow

# Import from JSON
to-cli workflow import --file workflow.json --project PROJECT_ID

# Import from YAML
to-cli workflow import --file workflow.yaml --project PROJECT_ID

# Import with overwrite
to-cli workflow import --file workflow.json --project PROJECT_ID --force

Backup and Restore

# Backup entire project
to-cli project backup PROJECT_ID --output backup.zip

# Restore project
to-cli project restore --file backup.zip --project PROJECT_ID

# Backup all projects
to-cli backup --all --output all-projects-backup.zip

Scripting Examples

Execute Workflow and Get Results

#!/bin/bash

# Variables
WORKFLOW_ID="wf_123"
TIMEOUT=3600

# Execute workflow
echo "Starting workflow execution..."
RESULT=$(to-cli workflow execute $WORKFLOW_ID \
  --env ENV=production \
  --timeout $TIMEOUT \
  --output json)

# Extract execution ID
EXEC_ID=$(echo $RESULT | jq -r '.execution_id')
echo "Execution ID: $EXEC_ID"

# Wait for completion
to-cli workflow watch $EXEC_ID

# Get final status
STATUS=$(to-cli workflow status $EXEC_ID --output json | jq -r '.status')
echo "Final Status: $STATUS"

# Get results
if [ "$STATUS" = "passed" ]; then
  echo "Workflow passed!"
  exit 0
else
  echo "Workflow failed!"
  exit 1
fi

Batch Execute Workflows

#!/bin/bash

# Array of workflow IDs
WORKFLOWS=("wf_001" "wf_002" "wf_003")

# Execute each workflow
for WF_ID in "${WORKFLOWS[@]}"; do
  echo "Executing workflow: $WF_ID"
  EXEC_ID=$(to-cli workflow execute $WF_ID --output json | jq -r '.execution_id')
  
  # Store execution ID
  echo $EXEC_ID >> executions.txt
done

# Monitor all executions
while IFS= read -r EXEC_ID; do
  STATUS=$(to-cli workflow status $EXEC_ID --output json | jq -r '.status')
  echo "Execution $EXEC_ID: $STATUS"
done < executions.txt

CI/CD Integration (GitHub Actions)

name: Run Workflow Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Install TO CLI
        run: |
          curl -fsSL https://download.test-orchestration.com/install.sh | bash
      
      - name: Set API Token
        run: to-cli auth set-token ${{ secrets.TO_API_TOKEN }}
      
      - name: Execute Test Workflow
        run: |
          to-cli workflow execute wf_production_tests \
            --env BRANCH=${{ github.ref }} \
            --timeout 3600
      
      - name: Check Results
        run: |
          STATUS=$(to-cli workflow status -l | jq -r '.[0].status')
          if [ "$STATUS" != "passed" ]; then
            exit 1
          fi

Create Project and Workflow

#!/bin/bash

# Create project
echo "Creating project..."
PROJECT=$(to-cli project create \
  --name "Automated Test Project" \
  --description "Project created via CLI" \
  --output json)

PROJECT_ID=$(echo $PROJECT | jq -r '.id')
echo "Project created: $PROJECT_ID"

# Create workflow
echo "Creating workflow..."
WORKFLOW=$(to-cli workflow create \
  --project $PROJECT_ID \
  --name "Automated Test Workflow" \
  --description "Workflow created via CLI" \
  --output json)

WORKFLOW_ID=$(echo $WORKFLOW | jq -r '.id')
echo "Workflow created: $WORKFLOW_ID"

# Execute workflow
echo "Executing workflow..."
EXEC=$(to-cli workflow execute $WORKFLOW_ID --output json)
EXEC_ID=$(echo $EXEC | jq -r '.execution_id')
echo "Execution started: $EXEC_ID"

Advanced Options

Logging and Debugging

# Enable verbose output
to-cli --verbose workflow execute WORKFLOW_ID

# Enable debug mode
to-cli --debug workflow execute WORKFLOW_ID

# Show API requests/responses
to-cli --trace workflow execute WORKFLOW_ID

# Log to file
to-cli workflow execute WORKFLOW_ID --log-file execution.log

Performance Tuning

# Set connection timeout (seconds)
to-cli --connect-timeout 30 workflow list

# Set read timeout (seconds)
to-cli --read-timeout 60 workflow execute WORKFLOW_ID

# Retry on failure
to-cli --retry 3 workflow execute WORKFLOW_ID

# Batch execution
to-cli workflow execute-batch workflows.txt

Custom Headers

# Add custom header
to-cli workflow list \
  --header "X-Custom-Header: value" \
  --header "Authorization: Bearer token"

Troubleshooting CLI

Common Issues

Command not found

# Verify installation
which to-cli
# or
to-cli --version

# Reinstall if needed
brew reinstall test-orchestration

Authentication failed

# Check token
to-cli auth verify

# Reset token
to-cli auth set-token NEW_TOKEN

# Check API URL
to-cli config show api_url

API connection error

# Check connectivity
to-cli --debug project list

# Test API endpoint
curl -H "Authorization: Bearer $TO_API_TOKEN" \
  https://api.test-orchestration.com/health

# Check proxy settings
echo $TO_PROXY_HOST
echo $TO_PROXY_PORT

Command Quick Reference

Command

Purpose

to-cli project list

List all projects

to-cli workflow list --project ID

List workflows

to-cli workflow execute ID

Execute workflow

to-cli workflow status ID

Check status

to-cli workflow watch ID

Monitor execution

to-cli config show

Show configuration

to-cli auth verify

Verify authentication

--help

Show command help

--output json

JSON output format

--verbose

Verbose output

Best Practices

✅ Do

Use environment variables - Secure credential storage
Store tokens safely - Don't hardcode in scripts
Use JSON output - For parsing in scripts
Set timeouts - Prevent hanging executions
Log executions - For debugging and auditing
Version control scripts - Track CLI automation
Test locally first - Before CI/CD integration

❌ Don't

Hardcode API tokens - Use env variables
Store credentials in git - Use secrets management
Ignore error codes - Check exit codes in scripts
Run without timeouts - Could hang indefinitely
Assume JSON structure - Parse with jq/grep
Mix credentials - Use one auth method

Getting Started - Basic concepts
Glossary - CLI terminology
FAQs - CLI questions
Troubleshooting - CLI issues

Summary

CLI provides command-line automation
Install via package manager or download
Authenticate with API token or login
Execute workflows via workflow execute command
Configure via config file or environment variables
Script for automation and CI/CD

Next: Learn about Glossary for terminology.

PreviousOverview NextGlossary

Last updated 11 days ago

hashtagOverview

hashtagInstallation

hashtagmacOS

hashtagLinux

hashtagWindows

hashtagVerify Installation

hashtagBasic Commands

hashtagHelp and Information

hashtagProject Commands

hashtagWorkflow Commands

hashtagAuthentication

hashtagAPI Token

hashtagLogin

hashtagLogout

hashtagWorkflow Execution

hashtagExecute Workflow

hashtagMonitor Execution

hashtagCancel Execution

hashtagConfiguration

hashtagConfiguration File

hashtagEnvironment Variables

hashtagConfiguration File Locations

hashtagOutput Formats

hashtagDefault (Table)

hashtagJSON Output

hashtagCSV Output

hashtagYAML Output

hashtagData Import/Export

hashtagExport Workflow

hashtagImport Workflow

hashtagBackup and Restore

hashtagScripting Examples

hashtagExecute Workflow and Get Results

hashtagBatch Execute Workflows

hashtagCI/CD Integration (GitHub Actions)

hashtagCreate Project and Workflow

hashtagAdvanced Options

hashtagLogging and Debugging

hashtagPerformance Tuning

hashtagCustom Headers

hashtagTroubleshooting CLI

hashtagCommon Issues

hashtagCommand Quick Reference

hashtagBest Practices

hashtag✅ Do

hashtag❌ Don't

hashtagRelated Topics

hashtagSummary

Overview

Installation

macOS

Linux

Windows

Verify Installation

Basic Commands

Help and Information

Project Commands

Workflow Commands

Authentication

API Token

Login

Logout

Workflow Execution

Execute Workflow

Monitor Execution

Cancel Execution

Configuration

Configuration File

Environment Variables

Configuration File Locations

Output Formats

Default (Table)

JSON Output

CSV Output

YAML Output

Data Import/Export

Export Workflow

Import Workflow

Backup and Restore

Scripting Examples

Execute Workflow and Get Results

Batch Execute Workflows

CI/CD Integration (GitHub Actions)

Create Project and Workflow

Advanced Options

Logging and Debugging

Performance Tuning

Custom Headers

Troubleshooting CLI

Common Issues

Command Quick Reference

Best Practices

✅ Do

❌ Don't

Related Topics

Summary