CLI Task Commands

The Forge CLI provides comprehensive task management commands for working with tasks in your ForgeHive projects:

Listing Available Tasks

View all tasks configured in your current project:

forge task:list

Example output:

Available tasks:
===============================================
• cloudflare:extract        - src/tasks/cloudflare/extract.ts
• cloudflare:getMetaData    - src/tasks/cloudflare/getMetaData.ts
• openAi:summary            - src/tasks/openAi/summary.ts
• pinecone:ingestAll        - src/tasks/pinecone/ingestAll.ts
• pinecone:insert           - src/tasks/pinecone/insert.ts
• pinecone:search           - src/tasks/pinecone/search.ts
• quality:calculate         - src/tasks/quality/calculate.ts
===============================================
Total tasks: 7
===============================================

What happens:

• Reads your forge.json configuration file
• Lists all defined tasks with their file paths
• Shows the total count of available tasks
• Tasks are sorted alphabetically for easy browsing

Getting Task Details

Get detailed information about a specific task including its schema, boundaries, and configuration:

forge task:describe <task-name>

Example:

forge task:describe cloudflare:extract

Example output:

===============================================
Task: cloudflare:extract
===============================================
Path: src/tasks/cloudflare/extract.ts
Handler: extract
Description: Extract markdown content from a URL using Cloudflare browser rendering

Schema:
-------
  • uuid (string): Unique identifier for the URL to extract

Boundaries:
-----------
  • findByUuid
  • getMarkdown
  • saveMarkdownContent
  • markAsError
===============================================

What happens:

• Bundles and loads the specified task
• Extracts schema information showing required parameters
• Lists all boundary dependencies the task uses
• Displays the task's description and configuration details

Running Tasks

Execute a task with the provided arguments:

forge task:run <task-name> --arg1 value1 --arg2 value2

Examples:

# Extract content from a URL
forge task:run cloudflare:extract --uuid f7eaa4e7-79f9-42c7-9a08-65989ccb8dec

# Generate AI summary
forge task:run openAi:summary --uuid 0c2a10bf-cf34-4c21-a3be-ba31ed96ddad

# Search vector database
forge task:run pinecone:search --query "Tell me about data governance" --count 5

# Calculate quality score
forge task:run quality:calculate --uuid "4eaa392c-43db-4174-b407-ffe394573cec"

What happens:

• Validates the task exists in forge.json
• Bundles the task for execution
• Runs the task with provided arguments
• Records execution logs locally in the logs folder
• Sends execution logs to the ForgeHive API if a profile is configured
• Returns the task result or throws an error if execution fails

Publishing Tasks

Publish a task to the ForgeHive registry to share with others:

forge task:publish <task-name>

Example:

forge task:publish quality:calculate

What happens:

• Bundles the task into a deployable package
• Compresses the bundle into a ZIP file
• Uploads task metadata and source code to ForgeHive
• Uploads the compressed bundle using a secure presigned URL
• Makes the task available in the ForgeHive registry

Requirements:

• Valid authentication profile must be configured
• Task must be defined in your forge.json
• Bundle size must not exceed 25MB

Downloading Tasks

Download a task from the ForgeHive registry to your local project:

forge task:download <task-name> --uuid <task-uuid>

Example:

forge task:download openAi:summary --uuid abc123-def456-ghi789

What happens:

• Downloads the task source code from ForgeHive using the UUID
• Creates the task file in the appropriate directory structure
• Updates your forge.json with the new task configuration
• Prevents overwriting if a task with the same name already exists

Task Naming:

• Simple names: myTask → creates myTask.ts
• Namespaced names: openAi:summary → creates openAi/summary.ts
• Complex namespaces: quality:calculateV4 → creates quality/calculateV4.ts

Replaying Task Executions

Replay a previous task execution from a fixture file:

forge task:replay <task-name> --path <fixture-path> [--cache <boundary-list>]

Example:

forge task:replay openAi:summary --path ./fixtures/summary-test.json --cache generateSummary,findByUuid

Parameters:

• descriptorName: The task to replay
• path: Path to the fixture file (absolute or relative to fixtures folder)
• cache: Optional comma-separated list of boundaries to cache/mock during replay

What happens:

• Loads the fixture file containing previous execution data
• Replays the task using the recorded input, output, and boundary data
• Can selectively cache specific boundaries to avoid external calls
• Sends replay logs to ForgeHive API if profile is configured
• Useful for debugging and testing task behavior

Removing Tasks

Remove a task from your project:

forge task:remove <task-name>

Example:

forge task:remove quality:calculateV1

What happens:

• Removes the task entry from forge.json
• Deletes the task file from the filesystem
• Displays confirmation of successful removal

Warning: This operation is irreversible. Make sure you have backups if needed.

Common Use Cases

Development Workflow

# List available tasks
forge task:list

# Get details about a specific task
forge task:describe cloudflare:extract

# Run a task locally
forge task:run cloudflare:extract --uuid f7eaa4e7-79f9-42c7-9a08-65989ccb8dec

# Publish when ready
forge task:publish cloudflare:extract

Testing and Debugging

# Run a task and capture logs
forge task:run openAi:summary --uuid 0c2a10bf-cf34-4c21-a3be-ba31ed96ddad

# Replay execution for debugging
forge task:replay openAi:summary --path logs/openAi:summary/latest.json

# Replay with cached boundaries to avoid external API calls
forge task:replay openAi:summary --path logs/openAi:summary/latest.json --cache generateSummary,findByUuid

Team Collaboration

# Download a task shared by a teammate
forge task:download pinecone:search --uuid team-shared-uuid

# Publish your improvements back
forge task:publish pinecone:search