Task Tracking

Relevant source files

The following files were used as context for generating this wiki page:

• src/commands/tasks.ts
• src/commands/tasks/statusCommand.ts
• __tests__/commands/tasks.test.ts
• src/commands/content/createCommand.ts
• __tests__/commands/content.test.ts
• src/client.ts
• src/bin.ts

Introduction

Task Tracking in the Recoup CLI is a specialized module designed to monitor the progress and outcome of asynchronous background processes, primarily those triggered by the content creation pipeline. Since operations like video generation are long-running, the CLI utilizes a "trigger and poll" pattern where users initiate a run and subsequently track its status using unique identifiers.

The system interfaces with a backend that manages "runs" (often associated with Trigger.dev), allowing users to retrieve real-time status updates, execution logs, and final output assets such as generated video URLs.
Sources: src/commands/tasks.ts:1-7, src/commands/tasks/statusCommand.ts:7-12, src/commands/content/createCommand.ts:64-70

Architecture and Data Flow

The task tracking architecture follows a standard request-response cycle over HTTP, where the CLI acts as a client to the Recoup API. Tasks are typically initiated by other command groups, such as the content command, which returns one or more runIds.

Interaction Flow

The following sequence diagram illustrates how a user initiates a content generation task and subsequently tracks its status.

The CLI provides a hint to the user immediately after a task is triggered, suggesting the exact command needed to track progress.
Sources: src/commands/tasks/statusCommand.ts:14-16, src/commands/content/createCommand.ts:68-70, __tests__/commands/content.test.ts:114-118

Command Components

Task tracking is encapsulated within the tasks command group, which currently implements the status subcommand.

The Status Command

The status command is the primary interface for tracking. It requires a --run <runId> argument and communicates with the /api/tasks/runs endpoint.

Argument/Option	Requirement	Description
--run <id>	Required	The unique identifier for the background task (Trigger.dev run ID).
--json	Optional	Returns the raw JSON response from the API.

Sources: src/commands/tasks/statusCommand.ts:7-12, __tests__/commands/tasks.test.ts:31-35

Implementation Logic

The status retrieval logic involves:

1. Request Construction: Performing a GET request to /api/tasks/runs with the runId passed as a query parameter.
2. Run Extraction: The API returns an array of runs; the CLI specifically looks for the first element (runs[0]).
3. Output Parsing: If the task is successful, the CLI drills into the output object to find a video object containing a signedUrl.

// Example of status parsing logic
const runs = Array.isArray(data.runs) ? data.runs : [];
const run = runs[0];
if (run) {
  console.log(`Status: ${run.status}`);
  if (run.output?.video?.signedUrl) {
    console.log(`Video URL: ${run.output.video.signedUrl}`);
  }
}

Sources: src/commands/tasks/statusCommand.ts:18-35, __tests__/commands/tasks.test.ts:52-65

Task States and Data Models

The system handles various states and data structures returned by the backend.

Task Run Object

Based on the API interactions, a task run object typically contains the following fields:

Field	Type	Description
id	String	Unique run identifier (e.g., run_abc123).
status	String	The current state (e.g., TRIGGERED, COMPLETED, FAILED).
output	Object	Container for task results, such as generated media.
output.video	Object	Metadata for generated video content.
output.video.signedUrl	String	A temporary, secure URL to download/view the result.

Sources: src/commands/tasks/statusCommand.ts:27-35, __tests__/commands/tasks.test.ts:52-58

State Transitions

While the CLI is a stateless observer, it distinguishes between three primary scenarios:

1. Run Found: Displays status and any available output.
2. Run Not Found: Explicitly logs "Run not found." when the API returns an empty list.
3. API Error: Handles request failures or unauthorized access by printing the error message and exiting with code 1.

Sources: src/commands/tasks/statusCommand.ts:21-25, __tests__/commands/tasks.test.ts:76-80, src/client.ts:73-80

Conclusion

Task Tracking serves as the bridge between instantaneous CLI commands and asynchronous backend operations. By providing a dedicated status command and clear "next-step" hints during task creation, the Recoup CLI ensures users can reliably monitor long-running workflows like video generation from start to finish.