# consensysdiligence/mythx-cli architecture

> Architecture diagram of the GitHub repository consensysdiligence/mythx-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/consensysdiligence/mythx-cli
- Repository: https://github.com/consensysdiligence/mythx-cli

## Overview

1. **Repository purpose**
   - This is a Python 3.6+ command-line client for the MythX smart-contract security analysis API.
   - It is a thin orchestration layer around the MythX/PythX interaction model: collect user input, submit or query analyses, and render results in multiple output formats.

2. **Primary boundary: local CLI vs external API**
   - The main architectural boundary is between the local CLI process and the remote MythX service.
   - Local code handles argument parsing, file discovery, input normalization, report formatting, and HTML rendering.
   - Remote calls are delegated through the PythX ecosystem to MythX endpoints for analyses, groups, reports, and version info.

3. **CLI entrypoint and command routing**
   - `mythx_cli/cli.py` is the top-level command surface exposed as `mythx`.
   - The repository is organized into subcommands, each with its own module tree:
     - `analyze`
     - `analysis`
     - `group`
     - `render`
     - `version`
   - This separation makes each command independently testable and keeps remote API actions isolated by domain.

4. **Authentication, configuration, and execution options**
   - The CLI accepts API credentials, username/password, config file, output target, and format flags.
   - The runtime also supports CI-oriented behavior such as failing with a non-zero exit code when high-severity findings are present.
   - These cross-cutting options affect all major commands and are likely resolved centrally before command execution.

5. **Analyze subsystem: building submission payloads**
   - `mythx_cli/analyze/` is responsible for turning local project inputs into analysis submissions.
   - It contains specialized handlers for different project types:
     - `solidity.py` for Solidity source inputs
     - `truffle.py` for Truffle project artifacts
     - `scribble.py` for Scribble-related handling
     - `command.py` as the command-level orchestration
     - `util.py` for shared helpers
   - This subsystem is the input-preparation layer before data is sent to MythX.

6. **Analysis subsystem: querying submitted jobs**
   - `mythx_cli/analysis/` provides read-only operations over existing analyses:
     - listing analyses
     - fetching a specific report
     - checking analysis status
   - Conceptually, this is the “monitoring and retrieval” side of the workflow after a submission has been created.

7. **Group subsystem: lifecycle management for analysis groups**
   - `mythx_cli/group/` manages groups of analyses:
     - open/create
     - list
     - close
     - status
   - This indicates that the tool treats analysis groups as first-class remote resources, separate from individual analysis jobs.

8. **Rendering and report presentation**
   - `mythx_cli/render/` turns API results into human-consumable HTML or markdown-like output.
   - The `templates/` directory contains layout and theme variants (`default`, `aesthetic`, HTML/MD layouts), so rendering is template-driven rather than hard-coded.
   - This subsystem is distinct from formatting: it produces richer report artifacts, likely for sharing or offline review.

9. **Formatter subsystem: terminal/file output shapes**
   - `mythx_cli/formatter/` handles output representations for CLI responses:
     - `simple_stdout`
     - `json`
     - `tabular`
   - The CLI supports both machine-readable and human-readable views, and the formatter layer sits between API response objects and final output destinations.
   - The presence of `formatter/util.py` and `base.py` suggests a common abstraction for consistent rendering across commands.

10. **Version command as a lightweight API probe**
   - `mythx_cli/version/` exposes a version/info command that likely queries service or client version metadata.
   - This is a small but separate command group, which keeps informational API access out of the analysis flows.

11. **Data flow through the system**
   - Typical flow is: user invokes CLI → command module parses inputs → optional project-specific analyzers gather and sanitize source data → MythX request is sent via PythX-backed API integration → response is transformed by formatter or renderer → output goes to stdout, file, or HTML artifact.
   - The same response data can be presented in several shapes, which is why output formatting is a distinct subsystem.

12. **Quality, testing, and documentation boundaries**
   - The repo includes a fairly complete `tests/` suite with command-specific fixtures and golden output files, which suggests behavior is validated by CLI contract and response formatting.
   - Documentation is extensive (`docs/` plus ReadTheDocs config), indicating that usage, command behavior, and response formats are part of the public architecture.
   - Packaging and release tooling (`setup.py`, `requirements*.txt`, CI configs, tox) show this is a distributable Python CLI rather than a long-running service.

Main entry points: [`mythx_cli/cli.py`](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/cli.py) (mythx), [`mythx_cli/analyze/command.py`](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/analyze/command.py) (Analyze), [`mythx_cli/formatter/base.py`](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/formatter/base.py) (Formatters), [`mythx_cli/render/command.py`](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/render/command.py) (Render)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli_core["CLI Core"]
  node_cli["mythx<br/>entrypoint<br/>[cli.py]"]
  node_core_util["Options<br/>[util.py]"]
end

subgraph group_analysis_flow["Analysis Flow"]
  node_analyze_cmd["Analyze<br/>command<br/>[command.py]"]
  node_solidity["Solidity<br/>input adapter<br/>[solidity.py]"]
  node_truffle["Truffle<br/>input adapter<br/>[truffle.py]"]
  node_scribble["Scribble<br/>input adapter<br/>[scribble.py]"]
  node_analysis_list["List<br/>query command<br/>[list.py]"]
  node_analysis_report["Report<br/>query command<br/>[report.py]"]
  node_analysis_status["Status<br/>query command<br/>[status.py]"]
  node_group_open["Open<br/>group command<br/>[open.py]"]
  node_group_list["Group List<br/>group command<br/>[list.py]"]
  node_group_close["Close<br/>group command<br/>[close.py]"]
  node_group_status["Group Status<br/>group command<br/>[status.py]"]
  node_version_cmd["Version<br/>info command<br/>[command.py]"]
end

subgraph group_output["Output"]
  node_render_cmd["Render<br/>[command.py]"]
  node_templates["Templates<br/>template set"]
  node_formatter["Formatters<br/>presentation layer<br/>[base.py]"]
  node_json_fmt["JSON<br/>formatter<br/>[json.py]"]
  node_stdout_fmt["Stdout<br/>formatter<br/>[simple_stdout.py]"]
  node_tabular_fmt["Tabular<br/>formatter<br/>[tabular.py]"]
end

subgraph group_external["Remote Service"]
  node_pythx[("PythX<br/>api client")]
  node_mythx_api[("MythX API<br/>remote service")]
end

subgraph group_validation["Validation"]
  node_tests["Tests<br/>test suite"]
end

node_cli -->|"reads options"| node_core_util
node_cli -->|"routes"| node_analyze_cmd
node_cli -->|"routes"| node_analysis_list
node_cli -->|"routes"| node_group_open
node_cli -->|"routes"| node_render_cmd
node_cli -->|"routes"| node_version_cmd
node_analyze_cmd -->|"prepares"| node_solidity
node_analyze_cmd -->|"prepares"| node_truffle
node_analyze_cmd -->|"prepares"| node_scribble
node_solidity -->|"submits"| node_pythx
node_truffle -->|"submits"| node_pythx
node_scribble -->|"submits"| node_pythx
node_analysis_list -->|"queries"| node_pythx
node_analysis_report -->|"queries"| node_pythx
node_analysis_status -->|"queries"| node_pythx
node_group_open -->|"mutates"| node_pythx
node_group_list -->|"queries"| node_pythx
node_group_close -->|"mutates"| node_pythx
node_group_status -->|"queries"| node_pythx
node_version_cmd -->|"queries"| node_pythx
node_render_cmd -->|"uses"| node_templates
node_render_cmd -->|"formats"| node_mythx_api
node_formatter -->|"implements"| node_json_fmt
node_formatter -->|"implements"| node_stdout_fmt
node_formatter -->|"implements"| node_tabular_fmt
node_json_fmt -->|"presents"| node_pythx
node_stdout_fmt -->|"presents"| node_pythx
node_tabular_fmt -->|"presents"| node_pythx
node_pythx -->|"calls"| node_mythx_api
node_tests -.->|"covers"| node_cli
node_tests -.->|"covers"| node_formatter
node_tests -.->|"covers"| node_render_cmd

click node_cli "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/cli.py"
click node_core_util "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/util.py"
click node_analyze_cmd "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/analyze/command.py"
click node_solidity "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/analyze/solidity.py"
click node_truffle "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/analyze/truffle.py"
click node_scribble "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/analyze/scribble.py"
click node_analysis_list "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/analysis/list.py"
click node_analysis_report "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/analysis/report.py"
click node_analysis_status "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/analysis/status.py"
click node_group_open "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/group/open.py"
click node_group_list "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/group/list.py"
click node_group_close "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/group/close.py"
click node_group_status "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/group/status.py"
click node_version_cmd "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/version/command.py"
click node_render_cmd "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/render/command.py"
click node_templates "https://github.com/consensysdiligence/mythx-cli/tree/master/mythx_cli/render/templates"
click node_formatter "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/formatter/base.py"
click node_json_fmt "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/formatter/json.py"
click node_stdout_fmt "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/formatter/simple_stdout.py"
click node_tabular_fmt "https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/formatter/tabular.py"
click node_tests "https://github.com/consensysdiligence/mythx-cli/tree/master/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_core_util toneBlue
class node_analyze_cmd,node_solidity,node_truffle,node_scribble,node_analysis_list,node_analysis_report,node_analysis_status,node_group_open,node_group_list,node_group_close,node_group_status,node_version_cmd toneAmber
class node_render_cmd,node_templates,node_formatter,node_json_fmt,node_stdout_fmt,node_tabular_fmt toneMint
class node_pythx,node_mythx_api toneRose
class node_tests toneIndigo
```

## Components

### CLI Core

Entry point, shared options, and command routing.

- [mythx](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/cli.py): entrypoint · Top-level CLI entrypoint and command router. · `mythx_cli/cli.py`
- [Options](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/util.py): config/options · Shared config, credentials, and execution options. · `mythx_cli/util.py`

### Analysis Flow

Submission, retrieval, and group lifecycle commands.

- [Analyze](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/analyze/command.py): command · Orchestrates analysis submission from local inputs. · `mythx_cli/analyze/command.py`
- [Solidity](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/analyze/solidity.py): input adapter · Builds analysis payloads from Solidity sources. · `mythx_cli/analyze/solidity.py`
- [Truffle](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/analyze/truffle.py): input adapter · Collects and normalizes Truffle project artifacts. · `mythx_cli/analyze/truffle.py`
- [Scribble](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/analyze/scribble.py): input adapter · Handles Scribble-related analysis preparation. · `mythx_cli/analyze/scribble.py`
- [List](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/analysis/list.py): query command · Lists submitted analyses. · `mythx_cli/analysis/list.py`
- [Report](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/analysis/report.py): query command · Fetches a specific analysis report. · `mythx_cli/analysis/report.py`
- [Status](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/analysis/status.py): query command · Checks analysis execution status. · `mythx_cli/analysis/status.py`
- [Open](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/group/open.py): group command · Creates or opens an analysis group. · `mythx_cli/group/open.py`
- [Group List](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/group/list.py): group command · Lists analysis groups. · `mythx_cli/group/list.py`
- [Close](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/group/close.py): group command · Closes an analysis group. · `mythx_cli/group/close.py`
- [Group Status](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/group/status.py): group command · Checks the state of an analysis group. · `mythx_cli/group/status.py`
- [Version](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/version/command.py): info command · Queries client or service version metadata. · `mythx_cli/version/command.py`

### Output

Formatters and report rendering.

- [Render](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/render/command.py): render command · Produces HTML or markdown-style report artifacts. · `mythx_cli/render/command.py`
- [Templates](https://github.com/consensysdiligence/mythx-cli/tree/master/mythx_cli/render/templates): template set · HTML and MD layout/theme templates. · `mythx_cli/render/templates`
- [Formatters](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/formatter/base.py): presentation layer · Shared output abstraction for CLI responses. · `mythx_cli/formatter/base.py`
- [JSON](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/formatter/json.py): formatter · Machine-readable JSON output. · `mythx_cli/formatter/json.py`
- [Stdout](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/formatter/simple_stdout.py): formatter · Simple human-readable terminal output. · `mythx_cli/formatter/simple_stdout.py`
- [Tabular](https://github.com/consensysdiligence/mythx-cli/blob/master/mythx_cli/formatter/tabular.py): formatter · Table-shaped CLI output. · `mythx_cli/formatter/tabular.py`

### Remote Service

Integration boundary to MythX via PythX.

- **PythX**: api client · Client boundary used to talk to MythX endpoints.
- **MythX API**: remote service · External analysis, group, report, and version service.

### Validation

Tests and contract fixtures.

- [Tests](https://github.com/consensysdiligence/mythx-cli/tree/master/tests): test suite · Contract and formatting regression tests with fixtures. · `tests`

## Connections

- mythx → Options: reads options · CLI resolves credentials, config, and runtime flags before dispatch.
- mythx → Analyze: routes · Dispatches analyze subcommands.
- mythx → List: routes · Dispatches analysis queries.
- mythx → Open: routes · Dispatches group commands.
- mythx → Render: routes · Dispatches rendering commands.
- mythx → Version: routes · Dispatches version/info command.
- Analyze → Solidity: prepares · Uses Solidity-specific input handling.
- Analyze → Truffle: prepares · Uses Truffle project handling.
- Analyze → Scribble: prepares · Uses Scribble-specific preparation.
- Solidity → PythX: submits · Builds and submits analysis payloads through the client layer.
- Truffle → PythX: submits · Builds and submits project-derived payloads through the client layer.
- Scribble → PythX: submits · Feeds annotated inputs into the client layer.
- List → PythX: queries · Fetches analysis listings from the remote service.
- Report → PythX: queries · Fetches report details from the remote service.
- Status → PythX: queries · Checks analysis status remotely.
- Open → PythX: mutates · Creates or opens remote groups.
- Group List → PythX: queries · Lists remote groups.
- Close → PythX: mutates · Closes remote groups.
- Group Status → PythX: queries · Checks group status remotely.
- Version → PythX: queries · Retrieves version metadata from the service or client boundary.
- Render → Templates: uses · Renders reports through template variants.
- Render → MythX API: formats · Turns API results into offline-friendly artifacts.
- Formatters → JSON: implements · Shared abstraction for JSON output.
- Formatters → Stdout: implements · Shared abstraction for terminal output.
- Formatters → Tabular: implements · Shared abstraction for tabular output.
- JSON → PythX: presents · Shapes remote response objects for machine consumers.
- Stdout → PythX: presents · Shapes remote response objects for humans.
- Tabular → PythX: presents · Shapes remote response objects into tables.
- PythX → MythX API: calls · Client library boundary to MythX endpoints.
- Tests → mythx: covers · Validates command behavior and CLI contracts.
- Tests → Formatters: covers · Validates output formatting and rendering.
- Tests → Render: covers · Validates report rendering and templates.
