OTinstaller

Install, run, update, and remove open-source command line tools by name.

You pick a tool from a list. OTinstaller downloads it into its own folder, runs it, and saves the output. You do not learn a different install method for each tool.

Status: early development. Not published to PyPI yet.

What you need

A Linux machine. Tested on Ubuntu 22.04 and 24.04, Debian 12, and Arch Linux. Kali Linux is checked by hand before a release.

Python 3.10 or newer, git, and the venv module. On Debian, Ubuntu and Kali, install that module with:

sudo apt install python3-venv git

Note: Some managed tools do not yet support Python 3.13+. The test matrix covers Python 3.10–3.12. If you encounter install failures on newer Python versions, try running otinstaller in a Python 3.12 virtualenv.

Ubuntu 26.04 LTS and other systems with Python 3.14

Ubuntu 26.04 LTS ships Python 3.14 by default, and other distributions now ship Python 3.14 too. otinstaller and some of its managed tools require Python 3.10–3.12, so on these systems install Python 3.12 explicitly and run otinstaller inside a virtualenv made with it:

sudo apt install python3.12 python3.12-venv
python3.12 -m venv ~/.otinstaller-venv
source ~/.otinstaller-venv/bin/activate
pip install otinstaller

Run source ~/.otinstaller-venv/bin/activate again in any new terminal before using otinstaller. otinstaller doctor prints the Python version it is running under and flags any registered tool that needs a different one.

Install OTinstaller

These commands install otinstaller itself. Run them in this repository's folder. A virtualenv is a private Python folder, so this install does not change the Python that came with the system.

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

otinstaller should now be on your path. A new terminal does not keep that. Run source .venv/bin/activate again from this folder if the next command says otinstaller: command not found.

For system-wide installation, use pipx install otinstaller (or pipx install . from this directory). This provides the otinstaller and ot commands on your PATH without a virtualenv.

Check the machine with:

otinstaller doctor

doctor prints [ok] or [problem] for Linux, Python, git, and venv. Fix any [problem] line before you continue. It often tells you the package to install.

Run your first tool

init creates ~/.otinstaller/ and shows a responsible-use notice. It asks Do you accept? [y/N]. Type y and press Enter. Nothing can be installed until you do.

otinstaller init

Sherlock searches for a username. This install asks Install? [y/N]. The capital N means Enter alone means no. Type y to continue.

otinstaller install sherlock
otinstaller run sherlock -- someexampleuser123

The -- marks where otinstaller's own options end. Everything after it is passed to Sherlock. When the run finishes, otinstaller prints a path under results/ in the folder where you ran the command. That file is the tool's output.

To try a different tool, use its name from the guide in place of sherlock.

Typed inputs

Instead of remembering each tool's flags, you can use typed input prefixes:

• u: username (e.g., u:johndoe)
• e: email (e.g., e:john@example.com)
• p: phone (e.g., p:+15551234567)
• d: domain (e.g., d:example.com)
• url: URL (e.g., url:https://example.com)
• q: text query (e.g., q:search terms)
• geo: coordinates (e.g., geo:32.22,-110.97)
• tg: Telegram channel (e.g., tg:channelname)
• lat: latitude (e.g., lat:37.7749)
• lng: longitude (e.g., lng:-122.4194)

Example:

otinstaller run sherlock -- u:johndoe
otinstaller run ghunt -- u:johndoe e:john@example.com

Each tool declares which input types it supports. Use otinstaller info <tool> to see the mapping.

All mode

Run every installed tool that supports a given input type:

otinstaller run --all u:johndoe
otinstaller run -a u:johndoe e:john@example.com

Only u, e, p, d, and url work with --all. Tools requiring API credentials are skipped unless --include-credentialed is passed.

Agent-friendly usage

Every command supports --json for machine-readable output. Commands never prompt when --yes or -y is given, or when stdin is not a terminal (CI mode). Exit codes are stable: 0 = success, 1 = error, 2 = invalid input, 130 = interrupted.

Command reference:

• otinstaller init — Initialize config and directories
• otinstaller install <tool>... — Install tools
• otinstaller remove <tool>... / --all — Remove tools
• otinstaller run <tool>... -- <args> — Run tools
• otinstaller run --all u:... — Run all matching tools
• otinstaller info <tool> — Show tool details
• otinstaller list / --installed — List tools
• otinstaller search <query> — Search tools
• otinstaller update / --all / --check-only — Update tools
• otinstaller check-updates — Check for updates (read-only)
• otinstaller auto <target> — Auto-detect type and run tools
• otinstaller example <tool> — Show example output
• otinstaller keys check — Check API keys
• otinstaller resume — Resume interrupted jobs
• otinstaller doctor — Run diagnostics

For AI agents: see llms.txt at the repository root.

Results

Results are saved automatically to ./results/<tool>/<target>/ using the filename pattern <YYYYmmdd-HHMMSS>_<tool>_<target>_<runid>.<ext> plus a .meta.json sidecar. The results directory can be overridden with --output or OTINSTALLER_RESULTS_DIR.

Example:

results/sherlock/testuser/20260929-123456_sherlock_testuser_abc123.txt
results/sherlock/testuser/20260929-123456_sherlock_testuser_abc123.meta.json

API keys

One env file holds all API keys: ~/.otinstaller/.env, permissions 600. Each tool only receives the keys it declares in its registry entry. Use otinstaller keys check to verify.

Resume

If a run or install is interrupted (crash, Ctrl+C, kill), otinstaller keeps a job marker in ~/.otinstaller/jobs/. Run otinstaller resume to detect and handle interrupted jobs:

• For installs: cleans up partial state and retries the install.
• For runs: reports the interrupted run and prints the command to rerun manually.

Use otinstaller resume --dry-run to see what would happen without making changes. Use --json for machine-readable output.

Finished jobs are skipped on resume (their marker is removed on completion). Partial output from interrupted runs is always kept in the results directory.

Dual-use tools and responsible use

Some tools are tagged dual-use in the registry. They can be used for legitimate research but also for misuse. Installing a dual-use tool prints a notice and requires confirmation unless --yes is given.

The global responsible-use notice is accepted on first otinstaller init. You can re-read it with otinstaller init any time.

Python version caveats

Some managed tools do not yet support Python 3.13+. The test matrix covers Python 3.10–3.12. Known affected tools:

• auto-archiver: requires Python <3.13 (dependency pdqhash needs a C++ compiler, no wheel for 3.13+)
• telepathy: requires Python <3.13 (dependency googletrans/httpx uses removed cgi module)

If you encounter install failures on Python 3.13+, run otinstaller in a Python 3.12 virtualenv.

License

MIT. See LICENSE.