website/content/docs/user-manual/cli.md

---
title: "CLI tool"
description: "Instructions to install mCaptcha CLI"
lead: ""
date: 2023-10-27T08:48:45+00:00
lastmod: 2023-10-27T08:48:45+00:00
draft: false
menu:
  docs:
    parent: "user-manual"
---

A CLI tool exists to compute mCaptcha challenges. It can be installed
from multiple sources:

## Install

### crates.io

The CLI tool is available on, [crates.io](https://crates.io), the Rust
language's package registry. Rust language toolchain is required to
install from crates.io, please see [rustup.rs](https://rustup.rs) for
Instructions to install it.

```bash
cargo install mcaptcha-cli
```

### Pre-compiled binaries

Nightly builds and stable releases are regularly published to
[dl.mcaptcha.org](https://dl.mcaptcha.org/mcaptcha/cli) for a variety of
CPU architectures and operating systems.

1. Download binary, checksum and GPG signature files

```bash
wget https://dl.mcaptcha.org/mcaptcha/cli/{VERSION}/{FILENAME}.tar.gz
wget https://dl.mcaptcha.org/mcaptcha/cli/{VERSION}/{FILENAME}.tar.gz.asc
wget https://dl.mcaptcha.org/mcaptcha/cli/{VERSION}/{FILENAME}.tar.gz.sha256
```

2. Verify checksum

```bash
sha256sum -c {FILENAME}.tar.gz.sha256
```

3. Download mCaptcha's GPG release keys and verify GPG signature

```bash
gpg --keyserver keyserver.ubuntu.com --recv 73DAC973A9ADBB9ADCB5CDC4595A08135BA9FF73
gpg --verify {FILENAME}.tar.gz.asc
```

4. Install Binary

```bash
tar -xvzf {FILENAME}.tar.gz && sudo cp {FILENAME}/mcaptcha-cli /usr/local/bin
```

### Build from source

1. Install Rust tool chain
   Please see [here](https://rustup.rs) for instructions.
2. Download source code

```bash
git clone https://git.batsense.net/mCaptcha/cli
```

3. Compile and install

```bash
cargo build --release && sudp cp ./target/release/mcaptcha-cli
/usr/local/bin
```

## Pass mCaptcha challenge

The CLI tool requires details about the challenge to work on it. The
tool can be used in three different modes compute challenge:

1. Protected Page: Compute mCaptcha challenge for the CAPTCHA at a
   protected page
2. Widget URL: Compute PoW for captcha at widget URL
3. (Developer mode) Offline: Computes PoW over given CAPTCHA parameters

### From protected page URL

The most convenient mode: copy the URL of the webpage which has the
mCaptcha widget (example: showcase.mcaptcha.org) and run the CLI tool
with it to get an authorization code:
Compute challenge using the URL

```bash
03:39 atm@lab cli ±|feat-parse-webpage ✗|→ mcaptcha-cli protected-page https://showcase.mcaptcha.org/
Authorization token: eRAZJiMrW58uDYA1s64Tmwq1u30HutuF
```

### Widget URL

If you have the widget URL (will be in format https://mcaptcha.example.org/widget?sitekey=randomstring), it can be used to solve challenge as well:

```bash
Compute PoW by fetching parameters from  CAPTCHA URL

Usage: mcaptcha-cli online --url <URL>

Options:
  -u, --url <URL>  URL of the CAPTCHA. Example:  https://example.org/widget?sitekey=foo
  -h, --help       Print help
```

Example usage:

```bash
13:32 atm@lab cli ±|online ✗|→ mcaptcha-cli online -u https://demo.mcaptcha.org/widget?sitekey=pHy0AktWyOKuxZDzFfoaewncWecCHo23
Authorization token: 3xleN26OctBuVu3X4t6CYyUjErhaxQvz
```

### [Developer mode] Offline

Useful while debugging mCaptcha configurations, works on raw challenge
parameters.

Help menu:

```bash
Compute PoW with offline parameters

Usage: mcaptcha-cli offline --salt <SALT> --phrase <PHRASE> --difficulty-factor <DIFFICULTY_FACTOR>

Options:
  -s, --salt <SALT>                            Salt with which PoW should be computed
  -p, --phrase <PHRASE>                        Phrase over which PoW should be computed
  -d, --difficulty-factor <DIFFICULTY_FACTOR>  Difficulty Factor
  -h, --help                                   Print help
```

Example usage:

```bash
13:28 atm@lab cli ±|online|→ mcaptcha-cli offline -s $(rand 32) -p $(rand 32) -d 50000
difficulty: 50000
nonce: 90507
original phrase: f351f333d44b2c6b5bf7f033b065bbb8fb5e9dd153bd402e43ed04425f5a3859
result: 340276562956196291522979356090220150471
```

Where rand is [this](https://github.com/realaravinth/dotfiles/blob/6fc6c87cc912e17488a35c0d3327ecf393221270/scripts/rand#L20) script.