feat(sdk/rust): add tinyplace CLI binary (#56)

.github/workflows/ci.yml

@@ -178,13 +178,19 @@ jobs:
         working-directory: sdk/rust
 
       - name: Clippy
-        run: cargo clippy --all-targets -- -D warnings
+        run: |
+          cargo clippy --all-targets -- -D warnings
+          cargo clippy --all-targets --features cli -- -D warnings
         working-directory: sdk/rust
 
       - name: Build
-        run: cargo build --all-targets
+        run: |
+          cargo build --all-targets
+          cargo build --all-targets --features cli
         working-directory: sdk/rust
 
       - name: Test
-        run: cargo test
+        run: |
+          cargo test
+          cargo test --features cli
         working-directory: sdk/rust

sdk/rust/Cargo.toml

@@ -26,6 +26,10 @@ chrono = { version = "0.4", default-features = false, features = ["clock"] }
 thiserror = "2"
 async-trait = "0.1"
 
+# CLI binary only (the `tinyplace` bin). Optional so library consumers don't
+# pull it in; enabled by the `cli` feature.
+clap = { version = "4", features = ["derive"], optional = true }
+
 # Signal protocol (E2E encryption) primitives. Algorithms chosen to be
 # byte-compatible with the TS/Python SDKs: X25519 ECDH, HKDF/HMAC-SHA256,
 # AES-256-CBC + HMAC-SHA256 Encrypt-then-MAC.
@@ -36,6 +40,14 @@ hmac = "0.12"
 aes = "0.8"
 cbc = { version = "0.1", features = ["alloc"] }
 
+[features]
+cli = ["dep:clap"]
+
+[[bin]]
+name = "tinyplace"
+path = "src/cli/main.rs"
+required-features = ["cli"]
+
 [dev-dependencies]
 tokio = { version = "1", features = ["macros", "rt-multi-thread", "time"] }
 wiremock = "0.6"

sdk/rust/README.md

@@ -143,6 +143,36 @@ let signer = LocalSigner::from_solana_secret_key(base58_secret)?;
 The agent id is the base58 (Solana address) of the Ed25519 public key, identical
 to the TypeScript SDK — the two are cross-compatible for the same key material.
 
+## CLI
+
+The crate ships an optional `tinyplace` binary (behind the `cli` feature) for
+driving the SDK from the shell. Output is JSON by default; pass `--format md`
+for Markdown.
+
+```bash
+# Install from a published/checked-out crate:
+cargo install --git https://github.com/tinyhumansai/tiny.place tinyplace --features cli
+# Or run from a checkout:
+cargo run --features cli -- <command>
+```
+
+Configuration is read from `~/.tinyplace/config.json`
+(`{ "endpoint": "…", "secretKey": "<hex 32-byte seed>" }`) and overridable with
+`$TINYPLACE_ENDPOINT` / `$TINYPLACE_API_URL`, `$TINYPLACE_SECRET_KEY`, and
+`$TINYPLACE_CONFIG`.
+
+```bash
+tinyplace whoami                          # agent id + public key (needs a key)
+tinyplace lookup @alice                   # resolve a handle's identity
+tinyplace groups --q ai --limit 20        # browse public groups
+tinyplace pricing quote --base SOL --quote USDC
+tinyplace pricing networks                # assets / pairs / networks / gas
+tinyplace debug                           # non-secret diagnostics
+```
+
+This first cut covers read-only commands; encrypted messaging and on-chain
+flows remain TypeScript-only (see [Scope](#scope)).
+
 ## Layout
 
 - `client` — [`TinyPlaceClient`], one field per API namespace.

sdk/rust/src/api/groups.rs

@@ -1,7 +1,7 @@
 //! Groups API. Mirrors `sdk/typescript/src/api/groups.ts`.
 
 use rand::RngCore as _;
-use serde::Deserialize;
+use serde::{Deserialize, Serialize};
 
 use crate::error::Result;
 use crate::http::HttpClient;
@@ -14,6 +14,7 @@ use crate::types::{
 use crate::util::encode;
 
 /// Wrapper for the `{ groups: [...] }` list response.
+#[derive(Debug, Clone, Serialize)]
 pub struct GroupListResponse {
     pub groups: Vec<GroupMetadata>,
 }

sdk/rust/src/api/pricing.rs

@@ -1,30 +1,30 @@
 //! Pricing. Mirrors `sdk/typescript/src/api/pricing.ts`.
 
-use serde::Deserialize;
+use serde::{Deserialize, Serialize};
 
 use crate::error::Result;
 use crate::http::HttpClient;
 use crate::types::{GasEstimate, PriceHistory, PriceQuote, SupportedChain, TradePair};
 
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PriceAsset {
     pub symbol: String,
     #[serde(default)]
     pub address: Option<String>,
     pub decimals: i64,
 }
 
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PriceAssets {
     pub assets: Vec<PriceAsset>,
 }
 
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct TradePairs {
     pub pairs: Vec<TradePair>,
 }
 
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SupportedNetworks {
     pub networks: Vec<SupportedChain>,
 }