Install the CLI
Use Python 3.10–3.14. For regular use across repositories, we recommend
pipx: it isolates dependencies while
making ptai available on PATH. Install pipx first, run pipx ensurepath, then
reopen your terminal if PATH changed.
pipx install ptai
ptai setup --mcp
Install your AI client's CLI first. Skip the MCP setup command for the demo or
standalone Ollama use. Upgrade an existing pipx installation with pipx upgrade ptai.
Alternative: an activated virtual environment
python -m pip install --upgrade ptai
ptai --version
Both ptai and pentest-ai are installed aliases. If the command is not found,
check pipx list or activate the environment where you installed it. Keep that
environment available after MCP registration. Avoid installing into an OS-managed
Python; use pipx or a virtual environment instead.
Try the bundled demo
ptai demo
The demo starts a local test application, checks its planted weaknesses, replays one finding, and compares the results with hardened routes. It does not need a model API key, a hosted account or an external target.
It writes ptai-demo-capsule.json in your working directory. The demo's temporary
server ends with the command; the capsule is an example of the evidence format,
not a permanently running target.
Choose how to run
Your AI client: connect through MCP. Codex and Claude Code supply their own model access and call Pentest-AI's testing tools.
ptai setup --mcp
Install your client's CLI first. After confirmation, setup configures all detected
supported clients in user-wide settings, including both Codex and Claude Code
when both are installed. It does not install clients or configure Ollama. Use ptai setup --mcp --dry-run to preview
configuration changes. Older releases may not detect Codex or Claude Code;
the client guide includes direct registration commands.
Standalone CLI: configure a model provider, such as OpenAI, Anthropic or
Ollama. For deterministic checks without a model, use --no-llm.
For a single repository, use the project-specific instructions in the client guide; the wizard currently has no project-scope option.
Choose an AI client or model →
Run an authorized engagement
Replace the example URL with a target you are explicitly allowed to test.
ptai start https://your-authorized-target.example --no-sync
The first-run consent prompt is part of setup. Read the scope and options before
starting. --no-sync keeps this run out of the legacy hosted-sync path if you
have credentials saved from an older installation.
For deterministic checks:
ptai start https://your-authorized-target.example --no-llm --no-sync
Optional scanner wrappers need the corresponding tools installed. Review
ptai tools --help and ptai start --help for your version.
Read the result
A candidate is a possible weakness. A verified finding has passed an independent oracle check under the tested conditions. A clean scan does not prove an application is free of vulnerabilities.
Keep the engagement ID printed by the CLI. Use it for reports and exports.
Get help
Use GitHub Issues for reproducible
bugs. Include the command, ptai --version, your operating system and sanitized
output. Keep credentials, private target details and proof capsules out of
public reports. For vulnerabilities in Pentest-AI, use the private reporting
route.