DukeInc/Kez
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: prefer cargo install + bare kez binary in examples

Browse Source 
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.
This commit is contained in:
Tudisco 2026-05-24 15:29:32 -06:00
parent b8a1306faf
commit eae98fead0
4 changed files with 46 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
README.md
View File

@ -53,7 +53,8 @@ Start here:
cd rust cd rust
cargo build cargo build
cargo test # 99 tests 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). Full guide: [`rust/README.md`](rust/README.md).

39
rust-sig-server/README.md
View File

@ -119,16 +119,20 @@ already does the job.
## Quick start ## Quick start
```sh ```sh
# Build # Build, then install the server binary to ~/.cargo/bin (one time)
cargo build --release cargo build --release
cargo install --path .
# Run with defaults — binds 0.0.0.0:7878, uses ./kez-sigchains.db # Run with defaults — binds 0.0.0.0:7878, uses ./kez-sigchains.db
cargo run --release kez-sig-server
# Or with explicit flags # 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: Configuration:
| Flag | Env var | Default | Meaning | | Flag | Env var | Default | Meaning |
@ -139,36 +143,35 @@ Configuration:
Logging via `RUST_LOG` (default `info`). Standard `tracing` filter syntax: Logging via `RUST_LOG` (default `info`). Standard `tracing` filter syntax:
```sh ```sh
RUST_LOG=debug,hyper=info cargo run RUST_LOG=debug,hyper=info kez-sig-server
``` ```
--- ---
## Try it: end-to-end POST → GET ## Try it: end-to-end POST → GET
Assumes you've also installed the `kez` CLI from
[`../rust/`](../rust/README.md#quick-start).
```sh ```sh
# 1. Start the server # 1. Start the server
cargo run --release & kez-sig-server &
# 2. Health check # 2. Health check
curl -s http://localhost:7878/v1/healthz curl -s http://localhost:7878/v1/healthz
# → {"status":"ok"} # → {"status":"ok"}
# 3. Generate a key + sign a seq-0 sigchain event using the kez CLI # 3. Generate a key, build a sigchain locally, push it to the server
# (Assumes you've built the main rust workspace too.) NSEC=$(kez identity new | awk -F': *' '/^Secret:/ {print $2; exit}')
cd ../rust kez sigchain add github:jason --nsec "$NSEC"
SEED=$(cargo run -q -p kez-cli -- identity new --key-type ed25519 \ kez sigchain add dns:jason.example --nsec "$NSEC"
| awk -F': *' '/^Secret:/ {sub(/ \(.*$/, "", $2); print $2}') kez sigchain publish --nsec "$NSEC" --server http://localhost:7878
echo "Seed: $SEED" # → server: posted 2 event(s), 0 already present
# 4. POST the event (today: hand-build via kez-core; a `kez sigchain` CLI # 4. Fetch the chain back as JSONL
# is on the roadmap and will make this one-line) PRIMARY=$(kez sigchain show --nsec "$NSEC" | awk '/^Primary:/ {print $2; exit}')
# For now see the integration tests in tests/http.rs for a worked example.
# 5. Fetch the chain back
PRIMARY="ed25519:<your-pubkey-hex>"
SCHEME=$(echo "$PRIMARY" | cut -d: -f1) 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 curl -s http://localhost:7878/v1/sigchains/$SCHEME/$ID
# → JSONL of every event in this chain # → JSONL of every event in this chain
``` ```

32
rust/README.md
View File

@ -35,26 +35,28 @@ rust/
└── README.md (this file) └── README.md (this file)
``` ```
Three crates, ~1,500 lines of Rust, **81 tests**. Three crates, ~2,500 lines of Rust, **99 tests**.
--- ---
## Quick start ## Quick start
```sh ```sh
# Build everything # Build, test, and install the `kez` binary to ~/.cargo/bin (one time)
cargo build cargo build
# Run the test suite
cargo test 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 ### End-to-end walkthrough
**1. Create a primary key.** **1. Create a primary key.**
```sh ```sh
cargo run -p kez-cli -- identity new kez identity new
``` ```
Outputs: Outputs:
@ -73,14 +75,14 @@ Pick the output format that fits where you'll publish:
```sh ```sh
# Markdown (for a GitHub gist or profile README) # 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 --nsec nsec1... --format markdown --out github-jason.kez.md
# Compact (one-liner for QR codes, chat, DNS TXT) # 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) # 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: **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: **4. Verify it** from anywhere:
```sh ```sh
cargo run -p kez-cli -- verify id github:jason kez verify id github:jason
``` ```
Output: Output:
@ -139,12 +141,12 @@ Fetch the proof for `<identifier>` from its native channel and verify it.
The identifier's `system:` prefix selects the channel plugin: The identifier's `system:` prefix selects the channel plugin:
```sh ```sh
cargo run -p kez-cli -- verify id dns:jason.example.com kez verify id dns:jason.example.com
cargo run -p kez-cli -- verify id github:jason kez verify id github:jason
cargo run -p kez-cli -- verify id nostr:npub1... kez verify id nostr:npub1...
cargo run -p kez-cli -- verify id bluesky:jason.bsky.social kez verify id bluesky:jason.bsky.social
cargo run -p kez-cli -- verify id ap:@jason@mastodon.social kez verify id ap:@jason@mastodon.social
cargo run -p kez-cli -- verify id mastodon:@jason@mastodon.social kez verify id mastodon:@jason@mastodon.social
``` ```
### `sigchain add <subject> --nsec | --ed25519-seed [--proof-url <url>]` ### `sigchain add <subject> --nsec | --ed25519-seed [--proof-url <url>]`

6
rust/crates/kez-cli/Cargo.toml
View File

@ -3,6 +3,12 @@ name = "kez-cli"
version = "0.1.0" version = "0.1.0"
edition.workspace = true 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] [dependencies]
anyhow.workspace = true anyhow.workspace = true
chrono.workspace = true chrono.workspace = true