Skip to content

cli_guide.md

Latest commit

 

History

History
467 lines (323 loc) · 8.46 KB

cli_guide.md

File metadata and controls

467 lines (323 loc) · 8.46 KB

FlowRunner CLI Guide

This guide provides detailed instructions for using the FlowRunner command-line interface (CLI).

Table of Contents

  1. Installation
  2. Configuration
  3. Authentication
  4. Flow Management
  5. Flow Execution
  6. Account Management
  7. Secrets Management
  8. Monitoring and Logging
  9. Advanced Usage

Installation

Building from Source

# Clone the repository
git clone https://github.com/tcmartin/flowrunner.git
cd flowrunner

# Build the CLI
go build -o flowrunner-cli cmd/flowrunner-cli/main.go

Adding to PATH

For convenience, add the FlowRunner CLI to your PATH:

# Linux/macOS
cp flowrunner-cli /usr/local/bin/flowrunner

# Or add the build directory to your PATH
export PATH=$PATH:/path/to/flowrunner

Configuration

The FlowRunner CLI can be configured using:

  1. Command-line flags
  2. Environment variables
  3. Configuration file

Command-line Flags

# Set the server URL
flowrunner --server http://localhost:8080

# Set the authentication token
flowrunner --token your-auth-token

# Set the output format
flowrunner --output json

Environment Variables

# Set the server URL
export FLOWRUNNER_SERVER=http://localhost:8080

# Set the authentication token
export FLOWRUNNER_TOKEN=your-auth-token

# Set the output format
export FLOWRUNNER_OUTPUT=json

Configuration File

Create a configuration file at ~/.flowrunner/config.yaml:

server: http://localhost:8080
token: your-auth-token
output: json

Authentication

Logging In

# Log in with username and password
flowrunner login --username user@example.com --password your-password

# Log in with username (password will be prompted)
flowrunner login --username user@example.com

Using API Keys

# Set API key
flowrunner config set api-key your-api-key

Checking Authentication Status

# Check if you're authenticated
flowrunner auth status

Flow Management

Creating Flows

# Create a flow from a YAML file
flowrunner flow create --file flow.yaml

# Create a flow with a specific name
flowrunner flow create --name "My Flow" --file flow.yaml

# Create a flow with a specific ID
flowrunner flow create --id my-flow-id --file flow.yaml

Listing Flows

# List all flows
flowrunner flow list

# List flows with a specific tag
flowrunner flow list --tag production

# List flows in JSON format
flowrunner flow list --output json

Getting Flow Details

# Get flow details
flowrunner flow get flow-id

# Get flow definition
flowrunner flow get flow-id --definition

Updating Flows

# Update a flow from a YAML file
flowrunner flow update flow-id --file flow.yaml

# Update flow metadata
flowrunner flow update flow-id --name "New Name" --description "New description"

Deleting Flows

# Delete a flow
flowrunner flow delete flow-id

# Force delete a flow (no confirmation)
flowrunner flow delete flow-id --force

Exporting Flows

# Export a flow to a YAML file
flowrunner flow export flow-id --output flow.yaml

# Export a flow to stdout
flowrunner flow export flow-id

Flow Execution

Running Flows

# Run a flow
flowrunner flow run flow-id

# Run a flow with input from a JSON file
flowrunner flow run flow-id --input input.json

# Run a flow with input from stdin
cat input.json | flowrunner flow run flow-id

# Run a flow with input from command line
flowrunner flow run flow-id --input-json '{"key": "value"}'

Listing Executions

# List all executions
flowrunner execution list

# List executions for a specific flow
flowrunner execution list --flow flow-id

# List recent executions
flowrunner execution list --limit 10

Getting Execution Details

# Get execution details
flowrunner execution get execution-id

# Get execution result
flowrunner execution get execution-id --result

Cancelling Executions

# Cancel an execution
flowrunner execution cancel execution-id

Account Management

Creating Accounts

# Create a new account
flowrunner account create --name "My Account"

# Create a new account with specific settings
flowrunner account create --name "My Account" --email user@example.com --role admin

Listing Accounts

# List all accounts
flowrunner account list

# List accounts with a specific role
flowrunner account list --role admin

Getting Account Details

# Get account details
flowrunner account get account-id

Updating Accounts

# Update account details
flowrunner account update account-id --name "New Name" --email new-email@example.com

Deleting Accounts

# Delete an account
flowrunner account delete account-id

# Force delete an account (no confirmation)
flowrunner account delete account-id --force

Secrets Management

Creating Secrets

# Create a secret
flowrunner secret create --key API_KEY --value your-api-key

# Create a secret for a specific account
flowrunner secret create --account account-id --key API_KEY --value your-api-key

# Create a secret from a file
flowrunner secret create --key CERTIFICATE --file certificate.pem

Listing Secrets

# List all secrets
flowrunner secret list

# List secrets for a specific account
flowrunner secret list --account account-id

Getting Secret Details

# Get secret details (without value)
flowrunner secret get API_KEY

# Get secret value
flowrunner secret get API_KEY --show-value

Updating Secrets

# Update a secret
flowrunner secret update API_KEY --value new-api-key

# Update a secret from a file
flowrunner secret update CERTIFICATE --file new-certificate.pem

Deleting Secrets

# Delete a secret
flowrunner secret delete API_KEY

# Force delete a secret (no confirmation)
flowrunner secret delete API_KEY --force

Monitoring and Logging

Viewing Logs

# View logs for an execution
flowrunner logs execution-id

# View logs for an execution with timestamps
flowrunner logs execution-id --timestamps

# View logs for an execution with a specific level
flowrunner logs execution-id --level error

# Follow logs in real-time
flowrunner logs execution-id --follow

Monitoring Executions

# Monitor an execution in real-time
flowrunner execution monitor execution-id

# Monitor an execution with a specific refresh interval
flowrunner execution monitor execution-id --interval 5s

Getting Metrics

# Get execution metrics
flowrunner metrics executions

# Get flow metrics
flowrunner metrics flows

# Get metrics for a specific time range
flowrunner metrics executions --from 2023-01-01 --to 2023-01-31

Advanced Usage

Batch Operations

# Run multiple flows
flowrunner flow run-batch --file flows.json

# Delete multiple flows
flowrunner flow delete-batch --file flows.json

Scheduling Flows

# Schedule a flow to run at a specific time
flowrunner flow schedule flow-id --time "2023-01-01T12:00:00Z"

# Schedule a flow to run with a cron expression
flowrunner flow schedule flow-id --cron "0 * * * *"

# List scheduled flows
flowrunner schedule list

# Delete a schedule
flowrunner schedule delete schedule-id

Importing and Exporting

# Export all flows
flowrunner flow export-all --directory flows/

# Import flows from a directory
flowrunner flow import --directory flows/

Plugins

# List available plugins
flowrunner plugin list

# Install a plugin
flowrunner plugin install plugin-name

# Update a plugin
flowrunner plugin update plugin-name

# Remove a plugin
flowrunner plugin remove plugin-name

Server Management

# Start the FlowRunner server
flowrunner server start

# Stop the FlowRunner server
flowrunner server stop

# Restart the FlowRunner server
flowrunner server restart

# Check server status
flowrunner server status

Configuration Management

# View current configuration
flowrunner config view

# Set a configuration value
flowrunner config set key value

# Get a configuration value
flowrunner config get key

# Reset configuration to defaults
flowrunner config reset

Debugging

# Enable debug mode
flowrunner --debug

# Run a flow in debug mode
flowrunner flow run flow-id --debug

# Validate a flow definition
flowrunner flow validate --file flow.yaml