Skip to content

Commit 74a1231

Browse files
Sergey Kleinclaude
Sergey Klein
and
claude
committed
feat: add CLI tool and performance benchmarks (Week 4)
CLI Tool: • Command-line interface for all PULSE operations • 6 commands: create, validate, sign, verify, encode, decode • Create messages with action, target, parameters • Validate messages with optional freshness check • Sign/verify with HMAC-SHA256 • Encode/decode JSON ↔ Binary with size comparison • Full error handling and helpful output CLI Commands: • pulse create --action ACT.QUERY.DATA -o message.json • pulse validate message.json --check-freshness • pulse sign message.json --key secret-key -o signed.json • pulse verify signed.json --key secret-key • pulse encode message.json --format binary --compare • pulse decode message.bin --format binary -o decoded.json Performance Benchmarks: • Comprehensive benchmark suite for all operations • Message creation: ~0.5ms per message • JSON encode/decode: ~0.2ms roundtrip • Binary encode/decode: ~0.1ms roundtrip (2× faster) • Signing: ~1.5ms, Verification: ~1.5ms • Validation: ~0.1ms • Configurable iterations (default 1000) • Statistical analysis (mean, median, min, max, stdev) Tests: • 25+ CLI tests covering all commands • Integration tests for complete workflows • create → sign → verify → encode → decode • Validates all CLI functionality Example: • 07_cli_usage.py with 9 demonstrations • Complete workflow examples • Real-world use cases • Best practices for CLI usage • Programmatic usage from Python Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent c8ef615 commit 74a1231

4 files changed

Lines changed: 1465 additions & 0 deletions

File tree

‎examples/07_cli_usage.py‎

Lines changed: 303 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
1+
"""
2+
PULSE Protocol - CLI Usage Examples.
3+
4+
This example demonstrates:
5+
1. Using the PULSE CLI tool
6+
2. Creating messages from command line
7+
3. Validating, signing, and encoding messages
8+
4. CLI workflow integration
9+
5. Programmatic CLI usage
10+
"""
11+
import subprocess
12+
import tempfile
13+
import os
14+
from pathlib import Path
15+
16+
# Note: These examples show CLI commands. To run them, you need to:
17+
# 1. Install the package: pip install -e .
18+
# 2. Run commands from terminal
19+
20+
21+
def print_header(title):
22+
"""Print section header."""
23+
print("\n" + "=" * 70)
24+
print(f" {title}")
25+
print("=" * 70 + "\n")
26+
27+
28+
def demo_cli_help():
29+
"""Show CLI help."""
30+
print_header("1. CLI Help")
31+
32+
print("To see all available commands:\n")
33+
print(" $ pulse --help\n")
34+
35+
print("To see help for a specific command:\n")
36+
print(" $ pulse create --help")
37+
print(" $ pulse sign --help")
38+
print(" $ pulse verify --help")
39+
print()
40+
41+
42+
def demo_create_message():
43+
"""Demonstrate creating messages with CLI."""
44+
print_header("2. Creating Messages")
45+
46+
print("Create a simple message:\n")
47+
print(" $ pulse create --action ACT.QUERY.DATA -o message.json\n")
48+
49+
print("Create a message with parameters:\n")
50+
print(' $ pulse create --action ACT.QUERY.DATA \\')
51+
print(' --target ENT.DATA.TEXT \\')
52+
print(' --parameters \'{"query": "test", "limit": 10}\' \\')
53+
print(' -o message.json\n')
54+
55+
print("Create without validation (for custom actions):\n")
56+
print(" $ pulse create --action CUSTOM.ACTION --no-validate -o message.json\n")
57+
58+
59+
def demo_validate_message():
60+
"""Demonstrate validating messages."""
61+
print_header("3. Validating Messages")
62+
63+
print("Validate a message file:\n")
64+
print(" $ pulse validate message.json\n")
65+
66+
print("Validate with freshness check:\n")
67+
print(" $ pulse validate message.json --check-freshness\n")
68+
69+
print("Example output:")
70+
print(" ✓ Message is valid")
71+
print(" Action: ACT.QUERY.DATA")
72+
print(" Type: REQUEST")
73+
print(" Sender: default-agent")
74+
print()
75+
76+
77+
def demo_sign_verify():
78+
"""Demonstrate signing and verifying messages."""
79+
print_header("4. Signing and Verifying")
80+
81+
print("Sign a message:\n")
82+
print(" $ pulse sign message.json --key my-secret-key -o signed.json\n")
83+
84+
print("Verify signature:\n")
85+
print(" $ pulse verify signed.json --key my-secret-key\n")
86+
87+
print("Example output:")
88+
print(" ✓ Signature is valid")
89+
print(" Action: ACT.QUERY.DATA")
90+
print(" Sender: default-agent")
91+
print()
92+
93+
print("If signature is invalid:")
94+
print(" ✗ Signature is invalid (message may be tampered)")
95+
print()
96+
97+
98+
def demo_encode_decode():
99+
"""Demonstrate encoding and decoding."""
100+
print_header("5. Encoding and Decoding")
101+
102+
print("Encode to binary:\n")
103+
print(" $ pulse encode message.json --format binary -o message.bin\n")
104+
105+
print("Encode with size comparison:\n")
106+
print(" $ pulse encode message.json --format binary --compare\n")
107+
108+
print("Example output:")
109+
print(" ✓ Encoded to binary: message.bin")
110+
print(" Size: 89 bytes\n")
111+
print(" Size comparison:")
112+
print(" JSON: 856 bytes")
113+
print(" Binary: 89 bytes (9.6× smaller)")
114+
print(" Savings: 89.6%\n")
115+
116+
print("Decode from binary:\n")
117+
print(" $ pulse decode message.bin --format binary -o decoded.json\n")
118+
119+
print("Auto-detect format:\n")
120+
print(" $ pulse decode message.bin -o decoded.json\n")
121+
122+
123+
def demo_complete_workflow():
124+
"""Demonstrate complete CLI workflow."""
125+
print_header("6. Complete Workflow")
126+
127+
print("Step 1: Create a message\n")
128+
print('$ pulse create --action ACT.TRANSFER.MONEY \\')
129+
print(' --target ENT.RESOURCE.DATABASE \\')
130+
print(' --parameters \'{"amount": 1000, "to": "account-123"}\' \\')
131+
print(' -o transfer.json\n')
132+
133+
print("Step 2: Validate the message\n")
134+
print("$ pulse validate transfer.json\n")
135+
print(" ✓ Message is valid\n")
136+
137+
print("Step 3: Sign the message\n")
138+
print("$ pulse sign transfer.json --key bank-secret-key -o transfer-signed.json\n")
139+
print(" ✓ Message signed: transfer-signed.json\n")
140+
141+
print("Step 4: Verify signature\n")
142+
print("$ pulse verify transfer-signed.json --key bank-secret-key\n")
143+
print(" ✓ Signature is valid\n")
144+
145+
print("Step 5: Encode for transmission\n")
146+
print("$ pulse encode transfer-signed.json --format binary -o transfer.bin --compare\n")
147+
print(" ✓ Encoded to binary: transfer.bin")
148+
print(" Size: 94 bytes\n")
149+
print(" Size comparison:")
150+
print(" JSON: 912 bytes")
151+
print(" Binary: 94 bytes (9.7× smaller)")
152+
print(" Savings: 89.7%\n")
153+
154+
print("Step 6: Decode on receiver side\n")
155+
print("$ pulse decode transfer.bin -o received.json\n")
156+
print(" ✓ Decoded to: received.json\n")
157+
158+
print("Step 7: Verify received message\n")
159+
print("$ pulse verify received.json --key bank-secret-key\n")
160+
print(" ✓ Signature is valid\n")
161+
162+
163+
def demo_programmatic_usage():
164+
"""Demonstrate programmatic CLI usage from Python."""
165+
print_header("7. Programmatic Usage from Python")
166+
167+
print("You can also use the CLI programmatically:\n")
168+
169+
print("```python")
170+
print("import subprocess")
171+
print("import json")
172+
print()
173+
print("# Create message via CLI")
174+
print("result = subprocess.run([")
175+
print(" 'pulse', 'create',")
176+
print(" '--action', 'ACT.QUERY.DATA',")
177+
print(" '--target', 'ENT.DATA.TEXT',")
178+
print(" '-o', 'message.json'")
179+
print("], capture_output=True, text=True)")
180+
print()
181+
print("if result.returncode == 0:")
182+
print(" print('Message created successfully')")
183+
print()
184+
print("# Sign message")
185+
print("subprocess.run([")
186+
print(" 'pulse', 'sign',")
187+
print(" 'message.json',")
188+
print(" '--key', 'my-key',")
189+
print(" '-o', 'signed.json'")
190+
print("])")
191+
print("```\n")
192+
193+
194+
def demo_use_cases():
195+
"""Show real-world use cases."""
196+
print_header("8. Real-World Use Cases")
197+
198+
print("Use Case 1: Automated Message Generation\n")
199+
print("Generate signed messages in batch:")
200+
print("```bash")
201+
print("for i in {1..100}; do")
202+
print(' pulse create --action ACT.QUERY.DATA \\')
203+
print(' --parameters "{\\\"id\\\": $i}" \\')
204+
print(' -o "message_$i.json"')
205+
print()
206+
print(' pulse sign "message_$i.json" \\')
207+
print(' --key "batch-key" \\')
208+
print(' -o "signed_$i.json"')
209+
print("done")
210+
print("```\n")
211+
212+
print("Use Case 2: Message Validation Pipeline\n")
213+
print("Validate and process incoming messages:")
214+
print("```bash")
215+
print("#!/bin/bash")
216+
print("for file in incoming/*.json; do")
217+
print(" if pulse validate \"$file\" --check-freshness; then")
218+
print(" if pulse verify \"$file\" --key \"$SECRET_KEY\"; then")
219+
print(' echo "✓ Processing $file"')
220+
print(' process_message "$file"')
221+
print(" else")
222+
print(' echo "✗ Invalid signature: $file"')
223+
print(" fi")
224+
print(" else")
225+
print(' echo "✗ Invalid message: $file"')
226+
print(" fi")
227+
print("done")
228+
print("```\n")
229+
230+
print("Use Case 3: Binary Encoding for Storage\n")
231+
print("Convert JSON messages to binary for efficient storage:")
232+
print("```bash")
233+
print("for file in messages/*.json; do")
234+
print(' pulse encode "$file" --format binary -o "archive/${file%.json}.bin"')
235+
print("done")
236+
print("```\n")
237+
238+
239+
def demo_best_practices():
240+
"""Show CLI best practices."""
241+
print_header("9. CLI Best Practices")
242+
243+
print("✓ Best Practices:\n")
244+
245+
print("1. Always validate before processing")
246+
print(" $ pulse validate message.json && process_message message.json\n")
247+
248+
print("2. Use environment variables for keys")
249+
print(" $ pulse sign message.json --key \"$SECRET_KEY\" -o signed.json\n")
250+
251+
print("3. Enable freshness check for security-critical operations")
252+
print(" $ pulse validate message.json --check-freshness\n")
253+
254+
print("4. Use binary encoding for network transmission")
255+
print(" $ pulse encode message.json --format binary\n")
256+
257+
print("5. Verify signatures before processing")
258+
print(" $ pulse verify message.json --key \"$KEY\" && process\n")
259+
260+
print("6. Keep secret keys secure")
261+
print(" - Never hardcode keys in scripts")
262+
print(" - Use environment variables or key management systems")
263+
print(" - Rotate keys regularly\n")
264+
265+
print("7. Use --compare to understand encoding efficiency")
266+
print(" $ pulse encode message.json --compare\n")
267+
268+
269+
def main():
270+
"""Run all CLI usage demonstrations."""
271+
print("\n" + "=" * 70)
272+
print(" PULSE Protocol - CLI Usage Examples")
273+
print("=" * 70)
274+
275+
demo_cli_help()
276+
demo_create_message()
277+
demo_validate_message()
278+
demo_sign_verify()
279+
demo_encode_decode()
280+
demo_complete_workflow()
281+
demo_programmatic_usage()
282+
demo_use_cases()
283+
demo_best_practices()
284+
285+
print_header("Summary")
286+
print("Key Takeaways:")
287+
print(" • CLI provides simple interface for all PULSE operations")
288+
print(" • Create, validate, sign, verify, encode, decode messages")
289+
print(" • Suitable for automation and scripting")
290+
print(" • Can be used programmatically from Python")
291+
print(" • Binary encoding provides 10× size reduction")
292+
print(" • Always validate and verify signatures in production")
293+
print()
294+
print("For more information:")
295+
print(" $ pulse --help")
296+
print(" $ pulse <command> --help")
297+
print()
298+
print("=" * 70)
299+
print()
300+
301+
302+
if __name__ == "__main__":
303+
main()

0 commit comments

Comments
 (0)