{"id":"c3977eb8-90dc-4f09-8f1f-cec640f2e024","slug":"bugtraceai-cli","kind":"mcp","name":"BugTraceAI-CLI","summary":"Agentic web-scanning engine with a terminal workspace, specialist tools, browser validation, reports, REST and MCP.","owner":"BugTraceAI","repoUrl":"https://github.com/BugTraceAI/BugTraceAI-CLI","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":184,"match":null,"fewStars":false,"format":"mcp","createdAt":null,"addedAt":"2026-10-14T05:14:11.604Z","logoUrl":"https://avatars.githubusercontent.com/u/247774386?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["browser-web","developer-tools","memory-knowledge"],"tags":["ai-agents","bug-bounty","penetration-testing","self-hosted","terminal","web-security"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T05:15:41.822Z","sample":false,"url":"https://conduits.dev/tools/bugtraceai-cli","language":"Python","transports":["stdio"],"install":{"pypi":"bugtraceai-cli"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# BugTraceAI-CLI\n\n[![Website](https://img.shields.io/badge/Website-bugtraceai.com-blue)](https://bugtraceai.com) [![Version](https://img.shields.io/badge/Version-4.0.34--beta-orange)](https://github.com/BugTraceAI/BugTraceAI-CLI/releases) [![Python](https://img.shields.io/badge/Python-3.10+-blue)](INSTALLATION.md) [![License](https://img.shields.io/badge/License-Apache--2.0-blue)](LICENSE) [![DeepWiki](https://img.shields.io/badge/DeepWiki-Ask%20AI-blue)](https://deepwiki.com/BugTraceAI/BugTraceAI-CLI)\n\n**Agentic web pentesting with a terminal workspace, specialist tools, browser validation, REST and MCP.**\n\nBugTraceAI-CLI is the web-scanning engine in the [BugTraceAI suite](https://github.com/BugTraceAI/BugTraceAI). It combines LLM-guided investigation with specialist tools and browser validation. Follow a scan and inspect its evidence in the terminal, connect [BugTraceAI-WEB](https://github.com/BugTraceAI/BugTraceAI-WEB) for a browser workspace, or automate the engine through REST and MCP.\n\n[Install](#install) · [See the terminal](#terminal-workspace) · [API and MCP](#api-and-mcp) · [Explore the suite](https://github.com/BugTraceAI/BugTraceAI)\n\nUse it only against applications you are authorized to test.\n\n## Terminal workspace\n\n![BugTraceAI 4.0.27-beta terminal pipeline, showing all six stages with offline sample data](docs/screenshots/tui-pipeline.png)\n\nThe TUI follows **Recon → Discovery → Strategy → Exploit → Validate → Report**.\nSet the target URL, Depth and Max URLs at the top. The phase strip, counters,\ntimings and scan controls stay visible while you switch views.\n\n<table>\n  <tr>\n    <td width=\"50%\"><strong>Findings</strong><br/>Search, sort and inspect evidence.<br/><img src=\"docs/screenshots/tui-findings.png\" alt=\"BugTraceAI Findings tab with searchable offline sample findings\"/></td>\n    <td width=\"50%\"><strong>Agents</strong><br/>Follow specialist states and queues.<br/><img src=\"docs/screenshots/tui-agents.png\" alt=\"BugTraceAI Agents tab with specialist cards, queues and processed counts\"/></td>\n  </tr>\n  <tr>\n    <td width=\"50%\"><strong>Provider · F7</strong><br/>Select the LLM provider and configure its API key.<br/><img src=\"docs/screenshots/tui-provider.png\" alt=\"BugTraceAI provider setup with an empty masked API-key field\"/></td>\n    <td width=\"50%\"><strong>Target Auth · F8</strong><br/>Use a Bearer token or a login YAML with optional TOTP.<br/><img src=\"docs/screenshots/tui-auth.png\" alt=\"BugTraceAI target authentication dialog with WEB-compatible login YAML\"/></td>\n  </tr>\n</table>\n\nPipeline, Findings and Agents captures use the built-in offline demo in\n4.0.27-beta. Sample findings illustrate the interface. Provider and Auth captures\nshow the actual setup dialogs without credentials.\n\n[Install](#install) · [Terminal controls](#terminal-controls) ·\n[Install with your AI coding agent](#install-with-your-ai-coding-agent) ·\n[API and MCP](#api-and-mcp) · [Configuration and reports](#configuration-and-reports)\n\n## Scan engine\n\nThe shared engine discovers endpoints, analyzes candidate findings, routes work\nto specialists and collects evidence through the validation/reporting stages.\nSpecialist coverage includes SQL injection, XSS, SSRF, IDOR, LFI, RCE, template\ninjection, XXE, JWT and redirect checks. Tool and browser evidence accompanies\nthe reported findings.\n\nProvider presets include OpenRouter, Anthropic and Z.ai. The WEB connects to the\nsame CLI engine for web scans and report access.\n\n## Install\n\nFor guided setup, use the [universal Launcher](https://github.com/BugTraceAI/BugTraceAI-Launcher)\n([current public release](https://github.com/BugTraceAI/BugTraceAI-Launcher/releases)). It can install WEB, CLI and the API-target engine\nindependently or in any combination:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/BugTraceAI/BugTraceAI-Launcher/main/install.sh | bash\n```\n\nFrom a CLI checkout, `./install.sh` opens the same menu with CLI suggested.\nThe component entry point requires Launcher 3.3.14 or newer; use the current public Launcher release for its\nprovider, Wizard and AI-assisted setup screens. Review the checked\nmodules and runtime before installing.\n\nIn the Launcher, enter and verify the required provider API key first. Then\nchoose **Install with Wizard** for guided setup, or **Install with AI** to have\nthe built-in assistant guide installation inside the TUI. The AI assistant\nuses OpenRouter or Anthropic provider tokens; use Wizard for Z.ai.\nSee the [current Launcher guide](https://github.com/BugTraceAI/BugTraceAI-Launcher#readme)\nfor supported module combinations and installation options. Enter the provider key locally;\nnever paste it into an AI coding-agent chat.\n\nFor a direct installation in this checkout, specify the options explicitly:\n\n```bash\ngit clone https://github.com/BugTraceAI/BugTraceAI-CLI.git\ncd BugTraceAI-CLI\n./scripts/install-runtime.sh --interface tui --runtime local --global yes\n```\n\n`--interface` selects the terminal TUI, web-scanning API/MCP, or both.\n`--runtime` selects local Python or Docker. The backend has no selection menu;\n`--global` and `--launch` default to `no`. Use `--global yes` to register `btai`,\nand `--launch yes` to open the TUI after installation in an interactive terminal.\nDirect installation includes only the CLI engine and selected interfaces.\n\n| Profile | Command |\n| --- | --- |\n| Local TUI + global command | `./scripts/install-runtime.sh --interface tui --runtime local --global yes` |\n| Docker API + MCP | `./scripts/install-runtime.sh --interface api --runtime docker --global no` |\n| Docker API + TUI + global command | `./scripts/install-runtime.sh --interface both --runtime docker --global yes` |\n| Update or repair the saved profile | `./scripts/install-runtime.sh --reuse` |\n\nLocal installation needs Python 3.10+. The installer prepares missing Linux\npip/venv tools and Docker/Compose for the Docker profile. On macOS, Docker\nsetup uses an existing Docker Desktop or Homebrew/Colima. Some specialist tools\nalso use Docker during local scans. TUI adds\nTextual; API adds FastAPI, Uvicorn, WebSockets and MCP. Existing environments\nretain previously installed packages when you change profiles.\n\nChoices are saved in `.bugtrace-install.env` without API keys. See\n[INSTALLATION.md](INSTALLATION.md) for prerequisites and runtime-specific setup.\n\nExplicit legacy `./install.sh` options and `--standalone [options]` delegate\nto this backend. Incomplete direct selections fail before installing anything.\nSee [INSTALLATION.md](INSTALLATION.md) for prerequisites and manual-agent setup.\n\n## Open the real TUI\n\n```bash\n./bugtraceai-cli\n# With global registration, open a new terminal and run from any directory:\nbtai\n```\n\nConfigure **Provider/F7**, enter your target, choose crawl limits and press\n**Start**. Opening the workspace does not start a scan. A real scan requires a\nprovider key. In Provider, uncheck **Save this key in local .env** to keep a new\nkey only for the current session.\n\nUse **Auth/F8** for the target website's credentials: a masked Bearer token or\na WEB-compatible login YAML, with optional TOTP/2FA. These target credentials\nstay in the TUI session. Auth can be edited before a scan or after it finishes.\nThe current YAML format and example are in\n[Target authentication](INSTALLATION.md#target-authentication).\n\nTo open a full interactive scan directly, or explicitly preview sample data:\n\n```bash\n./bugtraceai-cli full https://target.example\n./bugtraceai-cli tui --demo\n```\n\n### Docker TUI\n\n```bash\n# TUI-only Docker profile: interactive scanner, no published server ports\ndocker compose -f docker-compose.tui.yml run --rm scanner\n\n# Both interfaces installed: open the TUI inside the API container\ndocker compose exec api python3 -m bugtrace tui\n```\n\nThe global `btai` helper honors the selected local/Docker profile. Keep the\nregistered checkout at its installation path; rerun registration after moving\nit. API-only installations do not offer the global TUI command.\n\n## Terminal controls\n\n| View | Key | Purpose |\n| --- | --- | --- |\n| Pipeline | F2 | Scan stages, progress, counters and elapsed times |\n| Findings | F3 | Search, sort, inspect and export vulnerability evidence |\n| Agents | F4 | Specialist states, queues, counts and runtime details |\n| Timeline | F5 | Scan milestones and alerts |\n| Logs | F6 | Search engine output and filter by agent |\n| Provider | F7 | LLM provider and masked API-key setup |\n| Auth | F8 | Target Bearer token or login YAML |\n\n**F1** opens help; **Tab** moves focus; **Ctrl+S** starts; **Ctrl+X** stops;\n**Ctrl+E** exports captured findings; **Ctrl+Q** quits. Pause takes effect at the\nnext pipeline checkpoint. The top form accepts the target URL; the lower bar\naccepts commands such as `/help`, `/provider`, `/auth`, `/pause`, `/resume`,\n`/stop`, `/findings` and `/export`.\n\n## Install with your AI coding agent\n\nCopy this self-contained prompt into an agent with local terminal access,\nsuch as Claude Code, Cursor or Codex. It installs only the CLI module through\nthe universal Launcher, with the terminal TUI enabled:\n\n```text\nInstall BugTraceAI-CLI only on this machine using the official universal Launcher.\n\nFirst read:\nhttps://github.com/BugTraceAI/BugTraceAI-CLI#readme\nhttps://github.com/BugTraceAI/BugTraceAI-Launcher#readme\n\nFollow those instructions using the official installer:\nhttps://raw.githubusercontent.com/BugTraceAI/BugTraceAI-Launcher/main/install.sh\n\nSelect only BugTraceAI-CLI. Do not select BugTraceAI-API or BugTraceAI-WEB.\nEnable the terminal TUI. Use Install with Wizard and let me choose the\nruntime and whether to register the global btai command.\n\nPreserve any existing installation, configuration and data. Run the\nLauncher in my local interactive terminal. I will enter and verify the\nprovider API key there, choose ports and review the plan before installation.\nKeep credentials out of chat and logs. Do not start a scan.\n\nVerify TUI startup and exit in an interactive terminal. If I enable the\nglobal btai command, check it from a fresh shell. Verify health and MCP\nonly if those CLI services are enabled.\nReport the installation location, launch commands, checks completed\nand any checks still pending.\n```\n\n### Advanced: direct installation with your agent\n\nFor direct setup without the Launcher, use this separate prompt. It installs\nonly the CLI terminal workspace with local Python and the global btai command:\n\n```text\nInstall BugTraceAI-CLI directly from the official public repository:\nhttps://github.com/BugTraceAI/BugTraceAI-CLI\n\nFirst read:\nhttps://github.com/BugTraceAI/BugTraceAI-CLI#readme\nhttps://github.com/BugTraceAI/BugTraceAI-CLI/blob/main/INSTALLATION.md\n\nUse an existing checkout of that repository if available; otherwise clone it\ninto a new directory. Enter that directory and install a standalone terminal\nworkspace. Use the local Python runtime and register the current-user btai\ncommand. Perform the installation; do not start a scan.\n\nRead README.md and INSTALLATION.md first. Preserve existing configuration,\ncredentials and uncommitted changes. Do not replace this checkout or switch\nits repository or branch silently.\n\nFor a fresh install, review the documented CLI options, then run:\n./scripts/install-runtime.sh --interface tui --runtime local --global yes\n\nIf I ask for Docker or API/MCP, use the corresponding CLI installer options.\nDo not install BugTraceAI-WEB or BugTraceAI-API unless I explicitly request\nthose separate modules.\n\nHandle the required prompts and resolve setup errors using the repository\ninstructions. Keep system privilege/password prompts in my local terminal.\nNever ask me to paste credentials into chat or print existing secrets. I will\nconfigure an LLM provider locally through Provider/F7. Auth/F8 configures\ntarget login separately.\n\nVerify the version, saved profile and installed components. For TUI, verify\nstartup and quit in an interactive terminal when available; otherwise state\nthat visual verification is pending. Check btai registration and PATH in a\nfresh shell. For servers, check health and MCP on the actual configured\nports. Do not start a scan as part of installation.\n\nFinish with the installation directory, selected profile, checks performed\nand exact commands to open the installed interfaces.\n```\n\nSee [INSTALLATION.md](INSTALLATION.md) for profiles, Provider/F7, Auth/F8 and\ntroubleshooting. Installation does not require running a scan.\n\n## API and MCP\n\nInstall the `api` or `both` profile to use the engine without opening the TUI.\nFor local installations:\n\n```bash\n./bugtraceai-cli serve --port 8000\n# In a separate terminal, MCP defaults to STDIO:\n./bugtraceai-cli mcp\n# Optional HTTP/SSE transport:\n./bugtraceai-cli mcp --sse --host 127.0.0.1 --port 8001\n```\n\nThe API exposes `/health` and `/docs`. For Docker API/both profiles, the\ninstaller starts the API/MCP Compose services and records the selected ports\nin `.env`; use `docker compose up -d` to start them again. Connect an SSE client\nto `http://localhost:<MCP_PORT>/sse` using the actual configured MCP port.\n\nBugTraceAI-WEB uses the CLI API for scans, progress and reports. MCP clients can\ncontrol scans through the engine's tools. Configure provider credentials locally\nbefore scanning. See [API and MCP](INSTALLATION.md#api-and-mcp) for details.\n\n## Configuration and reports\n\n`bugtraceaicli.conf` contains the engine settings; provider credentials can be\nconfigured in local `.env`. The TUI offers Provider/F7 and Auth/F8 for scan setup.\nSee [public custom provider configuration](https://github.com/BugTraceAI/BugTraceAI-CLI/blob/main/docs/CUSTOM_PROVIDERS.md) for additional\nprovider options. Read the selected provider preset rather than relying on\nhistorical model names from older releases.\n\nReports are written beneath the configured report directory. Scan deliverables\ninclude `final_report.md`, `validated_findings.json`, `engagement_data.json`\nand `report.html`, with evidence and specialist artifacts as available.\n**Ctrl+E** or `/export` exports the findings captured by the TUI as JSON.\n\nExplicit command-line scans remain available for scripts:\n\n```bash\n./bugtraceai-cli scan https://target.example\n./bugtraceai-cli scan https://target.example --auth-config auth-config.yaml\n./bugtraceai-cli --help\n```\n\n## Documentation and releases\n\n- [Installation, profiles, authentication and terminal controls](INSTALLATION.md)\n- [Release notes](https://github.com/BugTraceAI/BugTraceAI-CLI/releases)\n- [BugTraceAI ecosystem](https://github.com/BugTraceAI/BugTraceAI)\n- [Launcher](https://github.com/BugTraceAI/BugTraceAI-Launcher)\n- [WEB dashboard](https://github.com/BugTraceAI/BugTraceAI-WEB)\n- [DeepWiki](https://deepwiki.com/BugTraceAI/BugTraceAI-CLI)\n\nThe public CLI is a beta. Use scans only on explicitly authorized targets.\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE), [LICENSE-HISTORY.md](LICENSE-HISTORY.md)\nand [NOTICE](NOTICE).\n\n[bugtraceai.com](https://bugtraceai.com) · [@yz9yt](https://github.com/yz9yt)\n\n## Amazon Bedrock (beta)\n\nBedrock Converse is available for the CLI and its WEB Provider panel. AWS role/profile authentication and optional Bedrock API keys are supported. [Setup, routing policy and pending AWS validation](BEDROCK.md).\n"}