CLI Dispatch & Command Invocation
Relevant source files
The following files were used as context for generating this wiki page:
Scoutline uses a centralized dispatching system to process command-line arguments and execute multimodal investigation tasks. The system decouples command logic from the execution environment using an invocation adapter pattern. This architecture ensures that core functions remain testable and consistent across different shell environments.
The lifecycle of a Scoutline command begins in the main entry point, which extracts global options, resolves provider requirements, and routes execution to specialized subcommand handlers.
Sources: packages/scoutline/src/index.ts, packages/scoutline/tests/cli.test.js
The Entry Point (main)
The main function serves as the primary orchestrator for the CLI. It accepts a string array of arguments (argv) and a dependency object containing the execution environment. The function follows a strict sequence: global option extraction, environment validation, and subcommand routing.
Global Option Extraction
Before routing to a specific command, Scoutline extracts global flags that affect all operations. This extraction happens via extractGlobalOptions, which identifies and removes these tokens from the argument stream.
| Option | Description | Impact |
|---|---|---|
--provider | Specifies the active research provider | Overrides provider discovery |
--output-format | Sets the serialization mode | Determines the CommandResult presentation used |
--max-chars | Defines an output budget | Triggers the compaction ladder for large payloads |
--help | Displays usage information | Short-circuits execution to print help text |
--version | Displays the package version | Prints the version from package.json |
Sources: packages/scoutline/src/index.ts, packages/scoutline/tests/output-budget-t4.test.js:419-450
Command Routing Flow
The dispatcher identifies the subcommand by inspecting the first non-option token. If the token matches a known command namespace, the dispatcher invokes the corresponding handler function.
The diagram shows the logical flow from argument parsing to final execution and output formatting.
Sources: packages/scoutline/tests/cli.test.js:106-114, packages/scoutline/tests/cache-command.test.js:358-375
Command Invocation Adapter
The CommandInvocationAdapter interface abstracts I/O operations. This abstraction allows the core logic to write to stdout/stderr or read from stdin without direct dependencies on Node.js globals like process.stdout.
Adapter Interface
The interface defines standard methods for interacting with the user and the terminal environment:
stdoutIsTTY: Boolean indicating if the output is a terminal.writeStdout(value: string): Sends data to the primary output stream.writeStderr(value: string): Sends diagnostic messages or errors.readStdin(): Captures input from a pipe or terminal.runQuietly(op: Function): Executes an operation while suppressing non-essential output.
Sources: packages/scoutline/src/command-invocation.ts
Node.js Implementation
The NodeCommandInvocationAdapter provides the production implementation. It maps the abstract methods to process.stdout, process.stderr, and process.stdin. It also handles TTY detection to determine when to use color or interactive prompts.
Sources: packages/scoutline/src/node-command-invocation-adapter.ts
Subcommand Dispatchers
Namespace dispatchers manage groups of related subcommands. For example, handleCache processes arguments for stats, clear, and prune. These dispatchers are responsible for parsing namespace-specific flags (like --older-than for pruning) and validating their values before calling the implementation.
This sequence illustrates how a namespace dispatcher parses local options and uses the adapter for output.
Sources: packages/scoutline/tests/cache-command.test.js:401-417
Command Results and Presentation Modes
All command handlers return a CommandResult object. This object separates the raw structured data from its various human-readable or machine-parsable representations.
Output Mode Resolution
Scoutline supports multiple output modes, selected via --output-format (or -O).
- data: Compact JSON of the raw payload.
- json: Expanded JSON including metadata and timing.
- pretty: Formatted, indented JSON for readability.
- tty: Human-centric text optimized for terminal display.
- markdown: Documentation-style representation of findings.
- refs: Specialized format for tool-use or citation tracking.
Sources: packages/scoutline/tests/cache-command.test.js:314-332, packages/scoutline/tests/output-budget-t4.test.js:490-520
Error Handling
When a command fails, the dispatcher catches the error and generates a standardized JSON error envelope if not in TTY mode. Errors are classified with specific codes like VALIDATION_ERROR, CONFIGURATION_ERROR, or UNSUPPORTED_OPTION.
Sources: packages/scoutline/tests/cli.test.js:106-114, packages/scoutline/tests/output-budget-t4.test.js:580-600
Conclusion
The CLI dispatch and command invocation system in Scoutline provides a structured gateway for multimodal research. By utilizing the CommandInvocationAdapter, the project ensures that command logic is environment-agnostic, enabling robust testing and consistent behavior across diverse execution contexts. The separation of CommandResult from its final presentation allows Scoutline to serve both human investigators and automated agents through the same command surface.