Command-line utility to control Tor.
Python Makefile
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
bin genesis Aug 3, 2014
carml temp_hs improvements Jun 26, 2018
doc version bump; use latest txtorcon Jun 26, 2018
notes tbb, etc Jan 11, 2017
.gitignore genesis Aug 3, 2014
.pyup.yml create config file Jan 11, 2018
LICENSE update license, and pypi build steps Aug 3, 2014
Makefile version bump; use latest txtorcon Jun 26, 2018
README.rst genesis Aug 3, 2014
meejah.asc genesis Aug 3, 2014
rtd-requirements.txt version bump; use latest txtorcon Jun 26, 2018


.. toctree::
   :maxdepth: 2


This code is intended as utilities mostly to help developers and Tor experts interact with their systems. Nobody has audited it for anonymitiy leaks (or worse). Use at your own risk.



carml is a command-line tool to query and control a running Tor (including Tor Browser Bundle). You can do things like:

  • list and remove streams and circuits;
  • monitor stream, circuit and address-map events;
  • watch for any Tor event and print it (or many) out;
  • monitor bandwidth;
  • run any Tor control-protocol command;
  • pipe through common Unix tools like grep, less, cut, etcetera;
  • download TBB through Tor, with pinned certs and signature checking;
  • ...even spit out and run xplanet configs (with router/circuit markers)!

It is written in Python and uses Tor's control-port via the txtorcon library.

Documentation at: or carmlion6vt4az2q.onion/ Code at:

In some ways, carml started as a dumping-ground for things I happened to make Tor do at least once from Python code. Are there things you wish you could easily make Tor do from the command-line? File an enhancement bug at GitHub!

carml is also easy to extend, even with system- or virtualenv- installed packages.

Feedback is appreciated -- pull-requests and bug-reports (including feature enhancements) welcome at GitHub or you can contact me in #tor-dev on OFTC or via meejah at meejah dot ca with the public-key contained in the source.

Some Quick Examples

(venv)meejah@machine:~$ carml circ --list
Connected to a Tor version " (git-c5a648cc6f218339)" (status: recommended).
   809: BUILT 29 minutes ago carmlfake0->~Unnamed->lobstertech
   810: BUILT 29 minutes ago ~carmelfake1->~toxiroxi->~SECxFreeBSD64
   811: BUILT 5 minutes ago carmelfake2->torpidsDEinterwerk->~rainbowwarrior
   813: BUILT 24 seconds ago carmlfake0->~arkhaios1->~IPredator
(venv)meejah@machine:~$ carml circ --delete 810
Connected to a Tor version " (git-c5a648cc6f218339)" (status: recommended).
Deleting circuit "810"...
...circuit 172 gone.
(venv)meejah@machine:~$ echo "hello world" | carml pastebin --once
12 bytes to share.
Launching Tor: connected.
People using Tor Browser Bundle can find your paste at (once the descriptor uploads):


If you wish to keep the hidden-service keys, they're in (until we shut down):
Awaiting descriptor upload...
Descriptor uploaded; hidden-service should be reachable.
Mon Jul 21 13:54:38 2014: Serving request to User-Agent "curl/7.37.0".
Shutting down.
(venv)meejah@machine:~$ carml downloadbundle --extract
Getting recommended versions from "".
   3.6.3-Linux, 3.6.3-MacOS, 3.6.3-Windows
tor-browser-linux64-3.6.3_en-US.tar.xz.asc: already exists, so not downloading.
tor-browser-linux64-3.6.3_en-US.tar.xz: already exists, so not downloading.
gpg: Signature made Fri 25 Jul 2014 11:20:02 AM MDT using RSA key ID 63FEE659
gpg: Good signature from "Erinn Clark <>"
gpg:                 aka "Erinn Clark <>"
gpg:                 aka "Erinn Clark <>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 8738 A680 B84B 3031 A630  F2DB 416F 0610 63FE E659
Signature is good.
Extracting "tor-browser-linux64-3.6.3_en-US.tar.xz"...
   20% extracted
   40% extracted
   60% extracted
   80% extracted
  100% extracted
Tor Browser Bundle downloaded and extracted.
To run:


carml is public domain. See for more information.

.. toctree::
   :maxdepth: 2