Using the CLI (aldecI)
Relevant source files
The following files were used as context for generating this wiki page:The aldecI command-line interface is the primary tool for interacting with the Aldeci (FixOps) platform from a terminal. It provides a user interface with functional parity to the FastAPI service, allowing for both local execution and remote interaction with a deployed Aldeci instance. The CLI is built using the Typer framework and is designed to be the main entry point for developers and CI/CD pipelines to ingest security artifacts, run analysis stages, and retrieve results.
The CLI supports a dual-backend architecture, controlled by the --backend flag. Users can choose to run operations using a local handler, which executes the logic directly on the user's machine, or a remote handler, which uses the Python SDK to communicate with a running FastAPI instance. This provides flexibility for different environments, from local development and testing to integration with a production deployment.
Sources: cli/aldecI.py, tools/docgen/api_cli_map.py:15-23, README.md:75
Architecture and Execution Flow
The aldecI CLI acts as a dispatcher. When a command is executed, it first determines which backend to use (local or remote) and then invokes the corresponding function to handle the request.
Backend Dispatch
The choice of backend dictates the entire execution path. The default behavior and specific implementation details are managed within the CLI's command functions.
The following diagram illustrates the high-level dispatch logic based on the --backend flag.
This diagram shows how the aldecI CLI command branches its execution flow depending on whether the backend is set to 'local' or 'remote'.
Sources: cli/aldecI.py, tools/docgen/api_cli_map.py:20-39
Local Execution Flow
When using --backend local, the CLI calls directly into the functions defined in apps/runtime/local_handlers.py. These handlers then orchestrate the various services required to fulfill the command.
This sequence diagram shows a typical local execution for a capability like stage.run.
Remote Execution Flow
When using --backend remote, the CLI utilizes the FixopsClient Python SDK. The SDK is responsible for constructing and sending a corresponding HTTP request to the remote FastAPI server, which then processes the request.
This sequence diagram shows a typical remote execution.
Core Components
The CLI's functionality is distributed across several key files that define its structure, capabilities, and execution logic.
| File/Module | Description |
|---|---|
cli/aldecI.py | Defines the main Typer application and the command structure (e.g., stage, ingest, risk). It parses CLI arguments and dispatches to the appropriate backend. |
apps/registry/execution_map.py | Contains the EXECUTION_REGISTRY, a dictionary that serves as the central source of truth for all platform capabilities. It maps each capability to its CLI command, API route, required services, and more. |
apps/runtime/local_handlers.py | Implements the functions for the local backend. Each handle_* function corresponds to a specific CLI capability. |
sdk/python/fixops_client.py | Contains the FixopsClient class, which is the Python SDK used by the remote backend to interact with the FastAPI service. |
tools/docgen/api_cli_map.py | A utility script that introspects the CLI and API to generate documentation. Its logic reveals the mapping between CLI commands, local handlers, and SDK methods. |
Sources: cli/aldecI.py, apps/registry/execution_map.py, apps/runtime/local_handlers.py, sdk/python/fixops_client.py, tools/docgen/api_cli_map.py
Capability Mapping
The EXECUTION_REGISTRY provides a canonical list of all capabilities within the Aldeci platform. The table below, derived from this registry, maps each capability to its corresponding CLI and API interfaces.
| Capability | Availability | CLI Syntax | API Route | Local Handler | SDK Method |
|---|---|---|---|---|---|
evidence.bundle | ✅ Available | aldecI evidence bundle | POST /api/v1/evidence/bundle | handle_evidence_bundle | evidence_bundle |
gate.check | ✅ Available | aldecI gate check | POST /api/v1/gate/check | handle_gate_check | gate_check |
graph.anomalies | ✅ Available | aldecI graph anomalies | GET /api/v1/graph/anomalies | handle_graph_anomalies | graph_anomalies |
graph.kev_in_last | ✅ Available | aldecI graph kev-in-last | GET /api/v1/graph/kev-in-last | handle_graph_kev | graph_kev |
graph.lineage | ✅ Available | aldecI graph lineage | GET /api/v1/graph/lineage | handle_graph_lineage | graph_lineage |
ingest.sarif | ✅ Available | aldecI ingest sarif | POST /api/v1/ingest/sarif | handle_ingest_sarif | ingest_sarif |
ingest.sbom | ✅ Available | aldecI ingest sbom | POST /api/v1/ingest/sbom | handle_ingest_sbom | ingest_sbom |
persona.explain | ❌ GAP: Enterprise only | aldecI persona explain | POST /api/v1/persona/explain | handle_persona_explain | persona_explain |
provenance.attest | ✅ Available | aldecI provenance attest | POST /api/v1/provenance/attest | handle_provenance_attest | provenance_attest |
provenance.verify | ✅ Available | aldecI provenance verify | POST /api/v1/provenance/verify | handle_provenance_verify | provenance_verify |
risk.score | ✅ Available | aldecI risk score | POST /api/v1/risk/score | handle_risk_score | risk_score |
stage.run | ✅ Available | aldecI stage run | POST /api/v1/stage/run | handle_stage_run | stage_run |
This table summarizes the mapping between high-level capabilities and their concrete implementations in the CLI, local runtime, and remote SDK. The availability is determined by the available flag in the registry.
Sources: tools/docgen/api_cli_map.py:29-39, 42-59, 196-207, apps/registry/execution_map.py
Example Usage
The following are sample commands showing how to invoke different capabilities.
Run an SSDLC stage:
# Runs the 'build' stage locally using an SBOM file
aldecI stage run --stage build --input path/to/sbom.json --backend local --overlay demo
Sources: README.md:64, tools/docgen/api_cli_map.py:165-169
Score risk from an SBOM:
# Scores risk for components in a normalized SBOM and outputs to a file
aldecI risk score --sbom artifacts/sbom/normalized.json --out artifacts/risk.json --backend local
Sources: README.md:47
Generate a provenance attestation:
# Creates a SLSA v1 attestation for a given artifact
aldecI provenance attest --artifact dist/fixops.tar.gz --out artifacts/attestations/fixops.json --backend local
Sources: README.md:48
Summary
The aldecI CLI is a powerful and flexible tool for interacting with the Aldeci system. Its dual-backend architecture provides parity between local development and remote production environments. By leveraging a central EXECUTION_REGISTRY, the CLI ensures a consistent and discoverable set of capabilities that map directly to both local handlers and the remote API, making it a cornerstone for user interaction and CI/CD automation.