Guide · Open source
How to use Ciphey: decode and identify encoded text
Updated · written with AI from the project's own documentation and checked against our catalogue data
Ciphey is an open-source command-line tool that takes encoded or encrypted text and tries chains of decoders until it finds readable plaintext. You do not need to know the key or the cipher name. This guide shows you how to install it, run your first decode, and use the flags that control how it searches and what it accepts.
Cipheybee-san/Ciphey · ★ 21.7k · MIT Install options & downloads Quick start
- 1Install Ciphey. Run cargo install ciphey if you have a Rust toolchain, or download a prebuilt binary from the releases page.
- 2Run a basic decode. Pass your encoded text with -t and answer y or N to the prompt.
- 3Complete first-run setup. Choose a colour theme, output style and wordlist option. Answers are saved to ~/.ciphey/config.toml.
- 4Limit or automate the search. Use -c to change the time limit from 5 seconds, or -d to accept the first plaintext without asking.
- 5Narrow results with a crib. Use -r with a regex, such as flag\{, to accept only matching plaintext.
Install Ciphey with Cargo or from prebuilt binaries
The simplest route is Cargo, Rust's package tool. Prebuilt binaries for Linux (x86_64), macOS (Intel and Apple silicon) and Windows (x86_64) are also on the releases page, each with a .sha256 checksum.
To build from source you need a Rust toolchain. Clone the repository and build the release binary, which ends up at target/release/ciphey.
cargo install ciphey
git clone https://github.com/bee-san/Ciphey
cd Ciphey
cargo build --release # the binary is target/release/cipheyRun your first decode
Pass the encoded text with -t. Ciphey searches decoder chains and, by default, asks you to confirm each candidate with a y/N prompt. The first time you run it, a short setup asks for a colour theme, how results should be shown and whether to use a wordlist, then saves your answers to ~/.ciphey/config.toml.
ciphey -t 'aGVsbG8gdGhlcmUgZ2VuZXJhbA=='Choose the flags you need
Most day-to-day use comes down to a few options. Run ciphey --help to see every option.
- -f secret.txt reads the input from a file.
- -d skips the y/N prompt and takes the first plaintext found, which is useful in scripts.
- -c 15 sets the search time limit to 15 seconds; the default is 5.
- -r 'flag\{' accepts only plaintext matching a regex, a crib.
- --wordlist words.txt also accepts any exact match from a wordlist.
ciphey -f secret.txt
ciphey -d -t '...'
ciphey -c 15 -t '...'
ciphey -r 'flag\{' -t '...'
ciphey --wordlist words.txt -t '...'Understand what Ciphey reports
Ciphey does not only decode. Each candidate plaintext is passed through LemmeKnow, a pattern matcher that recognises more than 120 formats, so the output can name what the result is, such as an IP address. Patterns that only check character sets and string length are ignored, because decoder output matches them constantly.
Results are cached in ~/.ciphey/database.sqlite, so repeating the same input is much faster the second time.
- Typical output names the decoders used, for example Base64 or hexadecimal.
- A candidate can be identified as a password, token, IP address, email, URL or CTF flag.
Know what Ciphey decodes and what it does not
Ciphey knows 24 decoders and crackers, covering base encodings, other encodings, ciphers and a few oddities. Its strength is stacked, layered encodings. It is a decoding and cracking tool, not a way to protect data, and the README does not claim it can break strong modern encryption with unknown keys.
- Base encodings: Base64, Base32, Base58, Base91, Base65536, Z85.
- Other encodings: hexadecimal, binary, URL, Morse code, Braille, A1Z26, Citrix CTX1.
- Ciphers: Caesar and ROT13, ROT47, Atbash, Vigenère, rail fence, reversed text.
- Oddities: Brainfuck, Morse or binary written with other symbols.
Use Ciphey as a library or through the Discord bot
The README also documents a library mode and an MCP server for AI assistants. If you do not want to install anything, the project points to a Discord server where you can type $ciphey followed by your text in the #bots channel. Run $help there to list commands.
What people use it for
- Decoding a multi-layer CTF puzzle such as ROT13 followed by hex and Base64.
- Checking what an encoded string found in a log or config actually contains, such as an IP address or a password in a mount command.
- Learning how common ciphers and encodings like Caesar, Vigenère and Morse behave.
- Quickly decoding several stacked Base64 layers without writing a script.
Frequently asked questions
Is Ciphey free and open source?
Yes. Ciphey is released under the MIT licence and its source is on GitHub at bee-san/Ciphey. The README does not list any price.
What do I need to install Ciphey?
The Rust toolchain is only needed if you build from source or use cargo install. Prebuilt binaries are available for Linux (x86_64), macOS and Windows (x86_64).
How do I install Ciphey?
Run cargo install ciphey, or clone the repository and run cargo build --release. You can also download a prebuilt binary from the releases page and check it against the .sha256 file.
Can Ciphey decrypt any encryption without the key?
No. The README describes it as decoding and cracking encodings and simple ciphers, and it does not claim it can break strong modern encryption with unknown keys. It is not a product for keeping data safe.
How is Ciphey different from Python Ciphey or CyberChef?
The README says Ciphey is written in Rust and is the successor to Python Ciphey, which it benchmarks against. CyberChef is listed as a comparable project; the README does not describe a head-to-head feature comparison with it.
Why does Ciphey ask me to confirm the result?
By default it shows the candidate plaintext and asks y/N before accepting it. Use -d to turn the prompt off, which is useful in scripts.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Ciphey suits CTF players, security students and pentesters who want to peel back stacked encodings quickly from the terminal. It is not a tool for protecting real data, and if you need a graphical interface, the README describes only a terminal workflow, so look at CyberChef instead.
Install options & downloads