From eae98fead010fe226310d0d07e686447e457f725 Mon Sep 17 00:00:00 2001 From: Tudisco Date: Sun, 24 May 2026 15:29:32 -0600 Subject: [PATCH] docs: prefer `cargo install` + bare `kez` binary in examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename the CLI binary from `kez-cli` to `kez` (via a [[bin]] section in the package's Cargo.toml; package name and `-p kez-cli` invocations stay the same so the workspace build, tests, and the cross-test harness are unaffected). Then update the READMEs to recommend `cargo install --path` once at the top of Quick Start, after which every example is the much shorter `kez ...` form. Mention `cargo run -p kez-cli --` as the dev iteration alternative for anyone who doesn't want to install. - rust/README.md: 11 `cargo run -p kez-cli --` → `kez` substitutions, plus a stale "81 tests" → "99 tests" fix. - README.md (root): Quick start gains a `cargo install` line. - rust-sig-server/README.md: Quick start uses `kez-sig-server` (post-install) with `cargo run` as the dev alternative; "Try it" section rewritten to use the actual `kez sigchain` CLI (which now exists) instead of the stale "hand-build via kez-core" workaround. --- README.md | 3 ++- rust-sig-server/README.md | 39 ++++++++++++++++++---------------- rust/README.md | 32 +++++++++++++++------------- rust/crates/kez-cli/Cargo.toml | 6 ++++++ 4 files changed, 46 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 8faf64a..73db254 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,8 @@ Start here: cd rust cargo build cargo test # 99 tests -cargo run -p kez-cli -- verify id github:jason +cargo install --path crates/kez-cli # → `kez` on PATH +kez verify id github:jason ``` Full guide: [`rust/README.md`](rust/README.md). diff --git a/rust-sig-server/README.md b/rust-sig-server/README.md index 6862986..1809a71 100644 --- a/rust-sig-server/README.md +++ b/rust-sig-server/README.md @@ -119,16 +119,20 @@ already does the job. ## Quick start ```sh -# Build +# Build, then install the server binary to ~/.cargo/bin (one time) cargo build --release +cargo install --path . # Run with defaults — binds 0.0.0.0:7878, uses ./kez-sigchains.db -cargo run --release +kez-sig-server # Or with explicit flags -cargo run --release -- --bind 127.0.0.1:8080 --db /var/lib/kez/chains.db +kez-sig-server --bind 127.0.0.1:8080 --db /var/lib/kez/chains.db ``` +For dev iteration without installing, use `cargo run --release --` in +place of `kez-sig-server`. + Configuration: | Flag | Env var | Default | Meaning | @@ -139,36 +143,35 @@ Configuration: Logging via `RUST_LOG` (default `info`). Standard `tracing` filter syntax: ```sh -RUST_LOG=debug,hyper=info cargo run +RUST_LOG=debug,hyper=info kez-sig-server ``` --- ## Try it: end-to-end POST → GET +Assumes you've also installed the `kez` CLI from +[`../rust/`](../rust/README.md#quick-start). + ```sh # 1. Start the server -cargo run --release & +kez-sig-server & # 2. Health check curl -s http://localhost:7878/v1/healthz # → {"status":"ok"} -# 3. Generate a key + sign a seq-0 sigchain event using the kez CLI -# (Assumes you've built the main rust workspace too.) -cd ../rust -SEED=$(cargo run -q -p kez-cli -- identity new --key-type ed25519 \ - | awk -F': *' '/^Secret:/ {sub(/ \(.*$/, "", $2); print $2}') -echo "Seed: $SEED" +# 3. Generate a key, build a sigchain locally, push it to the server +NSEC=$(kez identity new | awk -F': *' '/^Secret:/ {print $2; exit}') +kez sigchain add github:jason --nsec "$NSEC" +kez sigchain add dns:jason.example --nsec "$NSEC" +kez sigchain publish --nsec "$NSEC" --server http://localhost:7878 +# → server: posted 2 event(s), 0 already present -# 4. POST the event (today: hand-build via kez-core; a `kez sigchain` CLI -# is on the roadmap and will make this one-line) -# For now see the integration tests in tests/http.rs for a worked example. - -# 5. Fetch the chain back -PRIMARY="ed25519:" +# 4. Fetch the chain back as JSONL +PRIMARY=$(kez sigchain show --nsec "$NSEC" | awk '/^Primary:/ {print $2; exit}') SCHEME=$(echo "$PRIMARY" | cut -d: -f1) -ID=$(echo "$PRIMARY" | cut -d: -f2) +ID=$(echo "$PRIMARY" | cut -d: -f2-) curl -s http://localhost:7878/v1/sigchains/$SCHEME/$ID # → JSONL of every event in this chain ``` diff --git a/rust/README.md b/rust/README.md index 962be7f..2d07a11 100644 --- a/rust/README.md +++ b/rust/README.md @@ -35,26 +35,28 @@ rust/ └── README.md (this file) ``` -Three crates, ~1,500 lines of Rust, **81 tests**. +Three crates, ~2,500 lines of Rust, **99 tests**. --- ## Quick start ```sh -# Build everything +# Build, test, and install the `kez` binary to ~/.cargo/bin (one time) cargo build - -# Run the test suite cargo test +cargo install --path crates/kez-cli ``` +After that, the examples below use bare `kez`. For dev iteration without +installing, substitute `cargo run -p kez-cli --` for `kez` in any command. + ### End-to-end walkthrough **1. Create a primary key.** ```sh -cargo run -p kez-cli -- identity new +kez identity new ``` Outputs: @@ -73,14 +75,14 @@ Pick the output format that fits where you'll publish: ```sh # Markdown (for a GitHub gist or profile README) -cargo run -p kez-cli -- claim create github:jason \ +kez claim create github:jason \ --nsec nsec1... --format markdown --out github-jason.kez.md # Compact (one-liner for QR codes, chat, DNS TXT) -cargo run -p kez-cli -- claim create github:jason --nsec nsec1... --format compact +kez claim create github:jason --nsec nsec1... --format compact # JSON envelope (for /.well-known/kez.json) -cargo run -p kez-cli -- claim create github:jason --nsec nsec1... +kez claim create github:jason --nsec nsec1... ``` **3. Publish the proof** somewhere only the claimed account can publish to: @@ -96,7 +98,7 @@ cargo run -p kez-cli -- claim create github:jason --nsec nsec1... **4. Verify it** from anywhere: ```sh -cargo run -p kez-cli -- verify id github:jason +kez verify id github:jason ``` Output: @@ -139,12 +141,12 @@ Fetch the proof for `` from its native channel and verify it. The identifier's `system:` prefix selects the channel plugin: ```sh -cargo run -p kez-cli -- verify id dns:jason.example.com -cargo run -p kez-cli -- verify id github:jason -cargo run -p kez-cli -- verify id nostr:npub1... -cargo run -p kez-cli -- verify id bluesky:jason.bsky.social -cargo run -p kez-cli -- verify id ap:@jason@mastodon.social -cargo run -p kez-cli -- verify id mastodon:@jason@mastodon.social +kez verify id dns:jason.example.com +kez verify id github:jason +kez verify id nostr:npub1... +kez verify id bluesky:jason.bsky.social +kez verify id ap:@jason@mastodon.social +kez verify id mastodon:@jason@mastodon.social ``` ### `sigchain add --nsec | --ed25519-seed [--proof-url ]` diff --git a/rust/crates/kez-cli/Cargo.toml b/rust/crates/kez-cli/Cargo.toml index 18b5807..ff857bc 100644 --- a/rust/crates/kez-cli/Cargo.toml +++ b/rust/crates/kez-cli/Cargo.toml @@ -3,6 +3,12 @@ name = "kez-cli" version = "0.1.0" edition.workspace = true +# Binary is exposed as `kez` — short, the obvious name once installed. +# Build/run from the workspace with `-p kez-cli` (package name unchanged). +[[bin]] +name = "kez" +path = "src/main.rs" + [dependencies] anyhow.workspace = true chrono.workspace = true