PyExecutor CLI | Command-Line Interface Guide

✅ All 21 Commands Working

Config & Workflows

config show — Display settings
config set — Update config
workflows list — List all workflows
workflows get — Get details
workflows run — Execute workflow
workflows enable — Enable workflow
workflows disable — Disable workflow

Jobs & Logs

jobs list — List executions
jobs get — Get job details
jobs cancel — Cancel running job
jobs follow — Live log stream
logs job — Historical job logs
logs workflow — Workflow run logs

Secrets, Approvals & Utility

secrets list — List secrets
secrets get — Get secret value
secrets set — Create/update secret
secrets delete — Delete secret
approvals list — List approvals
approvals approve — Approve request
approvals reject — Reject request
approvals get — Get request details
--help — Command help

📦 Installation

Install the PyExecutor CLI from the local package:

cd cli/
pip install -e .

# Verify installation
pyexec --version
# Output: pyexec, version 1.0.0

Setup Authentication

# Configure your API endpoint and key
pyexec config-cmd set --api-url http://localhost:8000
pyexec config-cmd set --api-key your_token_here

# Verify configuration
pyexec config-cmd show

# You should see:
# api_url: http://localhost:8000
# api_key: ***token_last_4_chars (masked)
# timeout: 60

🔄 Workflows Management

✅ List all workflows

pyexec workflows list

# Filter by trigger type
pyexec workflows list --filter "trigger_type=cron"

# Filter by status
pyexec workflows list --filter "status=active"

# JSON output
pyexec workflows list --output json

# YAML output
pyexec workflows list --output yaml

# Export to file
pyexec workflows list --output json > workflows.json

✅ Get workflow details

# Get by workflow ID
pyexec workflows get 15

# Get by workflow name
pyexec workflows get "KPI Score Pipeline"

# JSON output
pyexec workflows get 15 --output json > workflow.json

✅ Enable/Disable workflows

# Enable a workflow
pyexec workflows enable 15

# Disable a workflow
pyexec workflows disable 15

# Disable by name
pyexec workflows disable "KPI Score Pipeline"

✅ Run workflow

# Run by ID
pyexec workflows run 15

# Run by name
pyexec workflows run "KPI Score Pipeline"

# Pass context variables
pyexec workflows run 15 --context key1=value1 --context key2=value2

# Pass context from JSON file
pyexec workflows run 15 --context-file payload.json

# Wait for completion
pyexec workflows run 15 --wait

# Wait and stream logs
pyexec workflows run 15 --wait --follow-logs

⚙️ Jobs & Executions

✅ List job executions

pyexec jobs list

# Filter by workflow
pyexec jobs list --filter "workflow=12"

# Filter by status
pyexec jobs list --filter "status=failed"

# Show only recent jobs (limit)
pyexec jobs list --filter "limit=50"

# JSON output
pyexec jobs list --output json

# YAML output
pyexec jobs list --output yaml

✅ Get job details

pyexec jobs get 907

# JSON output
pyexec jobs get 907 --output json

# Export to file
pyexec jobs get 907 --output json > job.json

✅ Follow running job (Live logs)

# Follow logs in real-time
pyexec jobs follow 907

# Shows step-by-step execution with live output
# Press Ctrl+C to stop following

# Example output:
# [INFO] Job #907 started.
# [STEP 1/3] Executing "Run Health Checks"
# [INFO] Running health checks...
# [CHECK] Auth Service      DOWN   343.0ms
# [CHECK] Payment Gateway   OK     106.0ms

✅ Cancel running job

# Cancel a running job
pyexec jobs cancel 907

# Note: Stopped jobs can be retried from the web UI

🚧 Retry failed job (Coming Soon)

# Retry with same inputs
# pyexec jobs retry 907

# Retry from specific step
# pyexec jobs retry 907 --from-step 2

⚠️ Not yet implemented.

🔐 Secrets Management

✅ Set secret

# Interactive prompt (secure)
pyexec secrets set SLACK_WEBHOOK_URL

# From command line (less secure)
pyexec secrets set API_KEY "sk_your_key_here"

✅ Get secret value

# Retrieve secret value (requires confirmation)
pyexec secrets get SLACK_WEBHOOK_URL

# Retrieve without confirmation
pyexec secrets get SLACK_WEBHOOK_URL --force

✅ List secrets

# List all secrets (without values - values are hidden for security)
pyexec secrets list

# JSON output
pyexec secrets list --output json

# YAML output
pyexec secrets list --output yaml

✅ Delete secret

# Delete a secret (requires confirmation)
pyexec secrets delete SLACK_WEBHOOK_URL

# Delete without confirmation
pyexec secrets delete SLACK_WEBHOOK_URL --force

✅ Approval Management

✅ List approval requests

# List all pending approvals
pyexec approvals list

# Filter by status
pyexec approvals list --status pending
pyexec approvals list --status approved
pyexec approvals list --status rejected

✅ Get approval details

# View full details for an approval request
pyexec approvals get 30

# Output as JSON
pyexec approvals get 30 --output json

✅ Approve a request

# Approve with a comment
pyexec approvals approve 30 --comment "Looks good, ship it"

# Approve (will prompt for comment)
pyexec approvals approve 30

✅ Reject a request

# Reject with a reason
pyexec approvals reject 30 --reason "Not ready for production"

# Reject (will prompt for reason)
pyexec approvals reject 30

📋 Logs & Debugging

✅ View live logs

# Stream job logs in real-time
pyexec jobs follow 907

# Press Ctrl+C to stop following

✅ View historical logs by job ID

# Get stored logs for a completed job
pyexec logs job 907

# Filter by level
pyexec logs job 907 --level error
pyexec logs job 907 --level warning
pyexec logs job 907 --level info

✅ View logs for a workflow (most recent run)

# Get logs from the most recent job for this workflow
pyexec logs workflow 12

# Also works with workflow name
pyexec logs workflow "Service Health Monitor"

⚙️ Configuration Management

✅ View configuration

pyexec config-cmd show

# Displays:
# api_url: http://localhost:8000
# api_key: ***n62g (masked for security)
# timeout: 60 (seconds)
# output_format: table (table, json, or yaml)

✅ Set configuration

# Set API endpoint
pyexec config-cmd set --api-url https://api.example.com

# Set API key
pyexec config-cmd set --api-key your_token_here

# Set request timeout
pyexec config-cmd set --timeout 120

# Set default output format
pyexec config-cmd set --output-format json

# View again to verify
pyexec config-cmd show

🌐 Platform Features via CLI

The CLI manages workflows, jobs, secrets, and approvals. These workflows can leverage all platform features including:

Multi-Language Scripts

Python, JavaScript, PowerShell, Bash, Go — all execute in isolated Docker containers

12 Step Types

Script, API, Database, Transform, AI, Condition, Loop, Notification, Approval, Subflow, Delay, Output

5 AI Providers

Gemini, OpenAI, Azure OpenAI, LM Studio, Ollama — with JSON mode and token tracking

Template Gallery

Clone pre-built workflow templates and configure them via the API

Git Version Control

Branches, commits, diffs, pull requests, and tags for workflows & scripts

RBAC & Analytics

Organizations, roles, permissions, API keys with scopes, and 10 analytics dashboards

📝 Real-World Examples

Example 1: Monitor Job Execution

#!/bin/bash

# Get job ID from the API
JOB_ID=$1

if [ -z "$JOB_ID" ]; then
  echo "Usage: $0 "
  exit 1
fi

# Follow job logs in real-time
echo "Following job #$JOB_ID (Press Ctrl+C to stop)"
pyexec jobs follow "$JOB_ID"

# Check final status
STATUS=$(pyexec jobs get "$JOB_ID" --output json | jq -r '.status')
echo "Job completed with status: $STATUS"

Example 2: Manage Secrets Securely

#!/bin/bash

# Create/update secrets
echo "Setting up application secrets..."
pyexec secrets set DATABASE_URL
pyexec secrets set API_KEY
pyexec secrets set WEBHOOK_SECRET

# List all secrets (without values)
echo "Configured secrets:"
pyexec secrets list

# Later, retrieve a secret (with confirmation)
echo "Retrieving database URL:"
DB_URL=$(pyexec secrets get DATABASE_URL --force)

# Use the secret
export DATABASE_URL="$DB_URL"

Example 3: List and Filter Workflows

#!/bin/bash

# Get all workflows as JSON
echo "Fetching all workflows..."
pyexec workflows list --output json > workflows.json

# Filter for active cron workflows
echo "Active scheduled workflows:"
pyexec workflows list --output json | jq '.[] | select(.trigger_type=="cron" and .is_active==true)'

# Get details of a specific workflow
WORKFLOW_ID=$(pyexec workflows list --output json | jq '.[0].id')
echo "Details of workflow $WORKFLOW_ID:"
pyexec workflows get "$WORKFLOW_ID" --output json | jq '.'

Example 4: Export Data for Analysis

#!/bin/bash

# Export all workflows
pyexec workflows list --output json > data/workflows.json
pyexec workflows list --output yaml > data/workflows.yaml

# Export all jobs
pyexec jobs list --output json > data/jobs.json

# Export secrets list (without values)
pyexec secrets list --output json > data/secrets.json

# Count statistics
WORKFLOW_COUNT=$(cat data/workflows.json | jq 'length')
JOB_COUNT=$(cat data/jobs.json | jq 'length')

echo "Exported $WORKFLOW_COUNT workflows and $JOB_COUNT jobs"

❓ Help & Support

Get help

# Global help
pyexec --help

# Command group help
pyexec workflows --help
pyexec jobs --help
pyexec secrets --help
pyexec config-cmd --help
pyexec logs --help

# Version info
pyexec --version

Output Formats

# Table format (default)
pyexec workflows list

# JSON format
pyexec workflows list --output json

# YAML format
pyexec workflows list --output yaml

# Change default format
pyexec config-cmd set --output-format json

Troubleshooting

API Error 404: Check API URL is correct with pyexec config-cmd show
Authentication Failed: Verify API key with pyexec config-cmd show
Connection Timeout: Increase timeout with pyexec config-cmd set --timeout 120
Command not found: Ensure CLI is installed with pip install -e . in the cli/ directory
No workflows found: Verify organization access and API key permissions

PyExecutor CLI Tool