Skip to main content

59. Direct System Access for CLI

Status: Accepted Date: 2025-07-06

Context​

For many administrative, debugging, and data migration tasks, interacting with the system through its public REST API is insufficient. The API is a public contract and may not expose the internal functions needed for low-level maintenance. We need a way for operators and developers to perform privileged operations directly on the system's internal components.

Decision​

The mercury-cli will be designed to have direct system access. It will not be a simple client that makes HTTP calls to the running application. Instead, the CLI will be a standalone NestJS application that bootstraps the entire main application's dependency injection container.

This means a CLI command will be able to directly inject and call any service, repository, or provider from the main application (e.g., ThothService, UserRepository, BybitProvider). It will operate with the full power and context of the backend application itself, bypassing the API layer completely.

Consequences​

Positive:

  • Ultimate Power & Flexibility: This provides an extremely powerful tool for any conceivable maintenance, debugging, or emergency intervention task. Any function that can be performed by the backend code can be triggered from the command line.
  • Efficiency: For data-intensive tasks like migrations or backfills, direct service and database access is vastly more efficient than making thousands of HTTP API calls.
  • Simplifies Scripting: Complex operational scripts are easier to write, as they can directly leverage the application's internal business logic instead of re-implementing it.

Negative:

  • Extremely Dangerous: This is a double-edged sword. The CLI can bypass all the validation and security checks present in the API layer. An incorrect command could easily lead to data corruption or other catastrophic failures.
  • Tightly Coupled: The CLI is now tightly coupled to the internal implementation details of the main application. Any significant refactoring of the internal services could break the CLI commands that depend on them.
  • Security Risk: Access to this CLI must be strictly controlled. A malicious actor with access to the CLI could do immense damage.

Mitigation:

  • Strict Access Control: Access to the production server environment where this CLI can be run will be heavily restricted to only essential, authorized personnel.
  • "Are you sure?" Prompts: For particularly destructive commands (e.g., deleting data, resetting state), the CLI will include interactive "are you sure?" prompts to prevent accidental execution.
  • Code Review and Testing: All CLI commands will be treated as production code, subject to the same code review and testing standards as any other part of the application.
  • Specific-Purpose Commands: We will favor creating many specific, single-purpose commands over creating a few generic, "do-everything" commands. This limits the potential blast radius of any single command.
  • Dry Run Mode: Where feasible, commands that make changes will include a --dry-run flag that reports what the command would do without actually doing it.