← Back to Blog Tutorials

Getting Started with QNSQY CLI

13 min read
Getting Started with QNSQY CLI - QNSQY post-quantum encryption guide

What This Guide Covers

This is a complete, step-by-step tutorial for people who have never used QNSQY before. By the time you finish reading, you will know how to:

  • Install QNSQY on Linux, macOS, or Windows
  • Encrypt a file so that only someone with the correct password can read it
  • Decrypt a file to get the original back
  • Generate signing and encryption keys for advanced workflows
  • Sign a file to prove it came from you and has not been tampered with
  • Verify a signature to confirm a file is authentic
  • Securely delete a file so it cannot be recovered, even by forensic tools
  • Understand the .qs file format and what the metadata means

No prior cryptography knowledge is required. Every command is shown with the exact text you type and the exact output you should see.

Step 1: Install QNSQY

QNSQY runs on Linux, macOS, and Windows. Pick the section for your operating system.

Linux (Debian, Ubuntu, Mint)

Download the .deb package from the download page and install it: 

sudo dpkg -i qnsqy_7.2.35-1_amd64.deb

On Fedora, CentOS, or RHEL, download the .rpm instead: 

sudo rpm -i qnsqy-7.2.35-1.x86_64.rpm

For any Linux distribution without installing a package, download the portable static binary, mark it executable, and run it: 

chmod +x qnsqy-7.2.35-x86_64-linux
./qnsqy-7.2.35-x86_64-linux --version

Windows

Download the .exe installer from the download page and run it. The installer adds qnsqy to your system PATH, so you can use it from Command Prompt or PowerShell immediately after installation.

Verify the Installation

Open a terminal (Terminal on Linux/macOS, Command Prompt or PowerShell on Windows) and type: 

qnsqy --version

You should see output like this: 

qnsqy 7.2.35 (free)

The word in parentheses shows your current tier. If you just installed, it will say "free." If you see this output, QNSQY is installed correctly and ready to use.

Step 2: Encrypt Your First File

Encryption turns a readable file into scrambled data that only someone with the correct password can unscramble. Think of it like putting a document inside a safe: anyone can see the safe exists, but nobody can read what is inside without the combination.

First, create a test file with some text inside it: 

echo "This is my secret message" > secret.txt

Now encrypt it: 

qnsqy encrypt -i secret.txt

QNSQY will ask you to type a password twice (once to set it, once to confirm). Your typing will not appear on screen for security: 

Enter password: ********
Confirm password: ********
Encrypting secret.txt...
Created secret.txt.qs (quantum-safe encrypted)

You now have two files in your directory: the original secret.txt and the encrypted secret.txt.qs. The .qs file is the encrypted version. If you try to open it with a text editor, you will see random-looking binary data. That is exactly what you want.

What Happened Behind the Scenes

When you ran that command, QNSQY performed several operations in sequence:

  1. Password hashing with Argon2id: Your password was processed by a deliberately slow algorithm that uses 128 MB of RAM. This makes it extremely expensive for an attacker to guess passwords by trying millions of them. NIST recommends Argon2id in their password guidelines (SP 800-63B).
  2. Key generation with ML-KEM-512 + X25519: QNSQY generated a hybrid encryption key using both a quantum-resistant algorithm (ML-KEM-512, standardized in NIST FIPS 203) and a classical algorithm (X25519). Both must agree for the key to work. This protects you now against classical attacks and in the future against quantum computers.
  3. Data encryption with AES-256-GCM: The actual file contents were encrypted using AES-256-GCM, a widely trusted authenticated encryption algorithm. "Authenticated" means it also detects if anyone has tampered with the encrypted data.
  4. Integrity check with BLAKE3: A fast cryptographic hash was computed to verify the file was not corrupted during encryption.

All of this happens automatically. You only had to type one command and pick a password.

Step 3: Decrypt a File

Decryption is the reverse operation: it takes the scrambled .qs file and restores the original. You need the correct password. 

qnsqy decrypt -i secret.txt.qs

Enter your password when prompted: 

Enter password: ********
Decrypting secret.txt.qs...
Decrypted to secret.txt

Your original file is restored. You can open secret.txt and confirm the contents match.

If you enter the wrong password, QNSQY tells you immediately: 

Decryption failed: Invalid password or corrupted file

QNSQY has built-in rate limiting: if someone tries wrong passwords repeatedly, it slows down responses and eventually locks out further attempts. This makes brute-force attacks (trying every possible password) impractical.

Step 4: Generate Signing and Encryption Keys

Passwords are one way to protect files. Keys are another. Think of it this way: a password is like a combination lock where both sides know the code. A key pair is like a mailbox: anyone can drop a letter in (using your public key), but only you can open the mailbox and read it (using your private key).

QNSQY uses two types of key pairs: signing keys (for proving authenticity) and encryption keys (for encrypting files to specific recipients).

Generate a Signing Key Pair

Signing keys let you attach a digital signature to a file. The signature proves two things: (1) the file came from you, and (2) nobody has changed it since you signed it. 

qnsqy keygen-sign -o mykey -n "Alice Signing Key"

Expected output: 

Generating ML-DSA-44 + Ed25519 hybrid signing keypair...
Public key:  mykey.pub
Private key: mykey
Label: Alice Signing Key
Keep your private key safe. Never share it.

This creates two files: mykey (your private key, keep this secret) and mykey.pub (your public key, safe to share with anyone). The key pair uses ML-DSA-44 (NIST FIPS 204) hybridized with Ed25519 for quantum-resistant plus classical security.

Generate an Encryption Key Pair

Encryption keys let someone encrypt a file specifically for you, without needing a shared password: 

qnsqy keygen-enc -o myenc -n "Alice Encryption Key"

Expected output: 

Generating ML-KEM-512 + X25519 hybrid encryption keypair...
Public key:  myenc.pub
Private key: myenc
Label: Alice Encryption Key
Keep your private key safe. Never share it.

You share myenc.pub with anyone who wants to send you encrypted files. They encrypt using your public key, and only your private key (myenc) can decrypt the result.

Step 5: Sign a File

Signing does not encrypt a file. It does not hide the contents. Instead, it attaches a mathematical proof that you (the person holding the private key) created or approved this exact file.

A real-world analogy: signing a file is like a notary stamp on a document. Everyone can still read the document, but the stamp proves it is authentic and unaltered. 

qnsqy sign -i report.pdf -k mykey

Expected output: 

Signing report.pdf with ML-DSA-44 + Ed25519...
Created report.pdf.qsig

The .qsig file is the detached signature. You distribute both the original file and the .qsig file together.

Step 6: Verify a Signature

When you receive a file and its .qsig signature, you can verify that it is authentic using the sender's public key: 

qnsqy verify -i report.pdf -k sender.pub

If the signature is valid: 

Signature valid: report.pdf
Signed by: Alice Signing Key
Algorithm: ML-DSA-44 + Ed25519 hybrid

If the file has been modified even slightly (a single bit changed), or if the signature was created by a different key: 

Signature INVALID: report.pdf
The file may have been tampered with or was not signed by this key.

This is critical for software distribution, legal documents, medical records, and any situation where you need proof that a file has not been altered.

Step 7: Securely Delete Files

When you delete a file normally (dragging to Trash on Mac, pressing Delete on Windows, or running rm on Linux), the data is not actually erased. The operating system just marks that space on disk as "available." Until something else writes over that space, the original data is still there. Forensic tools can recover it.

Think of it like tearing the table of contents out of a book. The chapters are all still there; you just removed the index. Someone patient enough can still read every page.

QNSQY's shred command overwrites the file data with random bytes multiple times before deleting: 

qnsqy shred secret.txt -f

The -f flag means "force" (do not prompt for confirmation). Output: 

Shredding secret.txt...
  Pass 1/3: Overwriting with random data...
  Pass 2/3: Overwriting with zeros...
  Pass 3/3: Overwriting with random data...
Securely deleted secret.txt

Three passes is the standard recommended by most security guidelines. After shredding, the file is genuinely gone, and professional data recovery services cannot retrieve it.

A common workflow is to encrypt a file and then shred the unencrypted original: 

qnsqy encrypt -i secret.txt && qnsqy shred secret.txt -f

This ensures only the encrypted version remains on disk.

Understanding the .qs File Format

Every .qs file starts with a header that stores metadata about the encryption. You can inspect this metadata without decrypting the file: 

qnsqy decrypt --show-metadata -i secret.txt.qs

Example output: 

File: secret.txt.qs
Format Version: 6.0
Tier: Free
AEAD Algorithm: Aes256Gcm
KEM Algorithm: MlKem512X25519Hybrid
Compression: None
Encryption Mode: Password Only
Argon2 Memory: 131072 KB (128 MB)
Original size: 26 bytes

Here is what each field means:

  • Format Version: The .qs format version. Newer versions of QNSQY can always read older formats.
  • Tier: Which tier was used to encrypt (Free, Pro, or Business). This does not restrict who can decrypt; anyone with the password can decrypt regardless of tier.
  • AEAD Algorithm: The symmetric encryption algorithm used. AES-256-GCM is the default. XChaCha20-Poly1305 is also available on every tier as an alternative.
  • KEM Algorithm: The key encapsulation method. MlKem512X25519Hybrid means ML-KEM-512 combined with X25519. Higher security levels (ML-KEM-768 and ML-KEM-1024) are available on Pro and Business tiers.
  • Compression: Whether the file was compressed before encryption. "None" means no compression was applied.
  • Encryption Mode: "Password Only" means you used a password. Other modes include recipient-based encryption using public keys.
  • Argon2 Memory: How much RAM the password hashing used. More memory means harder to brute-force. 128 MB is the Free tier default; Pro uses 256 MB and Business uses 512 MB.
  • Original size: The size of the file before encryption. The encrypted file will be slightly larger due to the header and authentication tags.

Common Options Explained

Encrypt with Compression

For text files, documents, and other compressible data, the -z flag enables zstd compression before encryption. This can significantly reduce file size: 

qnsqy encrypt -i database_dump.sql -z

Skip the -z flag for files that are already compressed (MP4 videos, JPEG images, ZIP archives). Compressing compressed data wastes CPU time without reducing size.

Custom Output Location

By default, the encrypted file is created in the same directory as the original with a .qs extension added. To write it somewhere else: 

qnsqy encrypt -i secret.txt -o /mnt/usb/encrypted_secret.qs

Encrypt with a Recipient's Public Key

Instead of a password, you can encrypt using someone's public encryption key. This means only the holder of the corresponding private key can decrypt it: 

qnsqy encrypt -i report.pdf --recipient bob_enc.pub

Bob would then decrypt with: 

qnsqy decrypt -i report.pdf.qs --key bob_enc

This is especially useful for sending encrypted files to others without needing to securely share a password.

Hash a File

Hashing computes a unique fingerprint of a file. If even one bit of the file changes, the hash changes completely. This is useful for verifying file integrity after a download or transfer: 

qnsqy hash -i report.pdf
BLAKE3: a1b2c3d4e5f6...  report.pdf

Later, you can verify the file has not changed: 

qnsqy hash-verify -i report.pdf --hash a1b2c3d4e5f6...

Troubleshooting Common Issues

"Permission denied"

This means you do not have write access to the location where QNSQY is trying to create the output file. Common fixes:

  • Write to your home directory instead: qnsqy encrypt -i /some/path/file.txt -o ~/encrypted_file.qs
  • On Linux, check file permissions with ls -la on the output directory
  • On Windows, make sure you are not writing to a system-protected folder like C:\Program Files

"File too large" (Free tier)

The free tier allows files up to 100 MB. If your file is larger, you have two options:

  • Split the file into smaller pieces, encrypt each one, and combine them later
  • Upgrade to Pro (25 GB limit) or Business (no limit) at the pricing page

"Wrong password" / "Invalid password or corrupted file"

QNSQY cannot recover your password. This is a deliberate security feature: if there were a backdoor for password recovery, attackers could use it too. If you cannot remember your password, the encrypted data is permanently inaccessible.

To avoid this situation:

  • Use a password manager to store your encryption passwords
  • For important files, consider using passphrase-based passwords (four or five random words strung together) since they are easier to remember while still being strong
  • Business tier supports M-of-N threshold encryption, where multiple people each hold a piece of the key, so no single person losing their password is a disaster

"Command not found: qnsqy"

The qnsqy binary is not in your system's PATH. This usually means:

  • On Linux, the installation did not add /usr/local/bin to your PATH, or you need to open a new terminal window after installing
  • On macOS, you may need to add the application's binary to your PATH manually
  • On Windows, close and reopen Command Prompt after running the installer

Encryption Seems Slow

QNSQY intentionally uses a memory-hard password hashing function (Argon2id). On the Free tier, it allocates 128 MB of RAM during password processing, which takes a noticeable moment. This is normal and is a core part of the security model: the same slowness that you experience also applies to anyone trying to guess your password, making brute-force attacks take millions of years.

If you are encrypting very large files (multiple gigabytes), the actual data encryption (AES-256-GCM) is fast, typically running at several hundred megabytes per second on modern hardware.

What to Learn Next

Now that you can encrypt, decrypt, sign, verify, and shred files, here are the next topics to explore:

Sources

  1. NIST FIPS 203: Module-Lattice-Based Key-Encapsulation Mechanism Standard (ML-KEM) - https://csrc.nist.gov/pubs/fips/203/final
  2. NIST FIPS 204: Module-Lattice-Based Digital Signature Standard (ML-DSA) - https://csrc.nist.gov/pubs/fips/204/final
  3. NIST SP 800-63B: Digital Identity Guidelines, Authentication and Lifecycle Management - https://pages.nist.gov/800-63-4/sp800-63b.html
  4. RFC 9106: Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications - https://www.rfc-editor.org/rfc/rfc9106
  5. NIST SP 800-38D: Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) - https://csrc.nist.gov/pubs/sp/800/38/d/final

Related Articles

Ready to Protect Your Files?

Download QNSQY and start encrypting in minutes.

Try QNSQY

Originally published at quantumsequrity.com/blog/getting-started-cli.