For AI Agents & Developers

This page describes how to use Stegstr programmatically: from the command line (CLI) or by understanding its capabilities and payload format. It is intended for AI agents (e.g. Claude, Cloudbot), scripts, and developers.

Capabilities

• Decode — Extract the hidden payload from a PNG that contains Stegstr data. Input: path to PNG. Output: raw payload bytes (often UTF-8 JSON after decryption).
• Embed — Encode a payload into a cover PNG. Input: cover image path, output path, payload (UTF-8 JSON string or base64). Output: path to the written PNG.

CLI (headless)

Build the CLI from the Stegstr repo (same codebase as the desktop app):

cd stegstr/src-tauri
cargo build --release --bin stegstr-cli

The binary is at target/release/stegstr-cli (or stegstr-cli.exe on Windows).

Decode

stegstr-cli decode <path_to.png>

Writes the raw payload to stdout. If the payload is valid UTF-8 JSON, it is printed as text; otherwise it is printed as base64:<data>. Exit code 0 on success, non-zero on error.

Embed

stegstr-cli embed <cover.png> -o <output.png> --payload <json_string>

Or read payload from a file: --payload @path/to/bundle.json. Payload can also be base64: --payload-base64 <base64_string>. Exit code 0 on success.

Payload format

Raw layer (what is embedded in the image):

• Magic: STEGSTR (7 bytes ASCII)
• Length: 4 bytes, big-endian
• Payload: The actual bytes (usually encrypted by the desktop app; CLI embeds raw bytes)

Decrypted payload (from the desktop app) is UTF-8 JSON:

{ "version": 1, "events": [ ... ] }

events are Nostr-style events (kind 1 notes, kind 4 DMs, kind 0 profiles, etc.). A JSON Schema for the bundle is in the repo. See How It Works for encryption (open vs recipients) and the full Detect/Embed flow.

Image format

PNG only (lossless). JPEG or other lossy formats will corrupt the hidden data.

Discovery

AI agents can discover Stegstr via:

• agents.txt — https://stegstr.com/agents.txt (capabilities, download links, key pages)
• This page — Linked from agents.txt as For-Agents

Links

How It Works · FAQ · GitHub · Getting Started · Downloads