cyberspace-cli

A CLI client for navigating Cyberspace v2.

This repo is intentionally separate from the current research/prototype code under ../v2/.

What this CLI does (today)

• Creates/loads an identity (Nostr Schnorr keypair)
• Creates and manages a local movement chain: a labeled series of Nostr-style JSON events
• Computes and stores v2 movement proofs (per-axis Cantor tree) in hop events

What this CLI does NOT do (yet)

• Publish events to relays
• Sign events (sig is currently left blank so we can sign at publish-time)

Install

Dev install

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .

Quick usage

For the extended guide (also available offline):

cyberspace help

For the full CLI / subcommand help:

cyberspace --help
cyberspace move --help
cyberspace target --help

Typical flow:

# create identity + genesis event (also selects this chain as active)
cyberspace spawn

# move locally (appends a hop event)
cyberspace move --by 1,0,0

# inspect your chain
cyberspace chain status
cyberspace history

Command reference

# open the upstream spec
cyberspace spec

# show built-in extended help
cyberspace help

# identity + chain genesis
cyberspace spawn
cyberspace spawn --from-key <nsec_or_32-byte-hex>
cyberspace spawn --chain mychain

# chain management
cyberspace chain list
cyberspace chain use mychain
cyberspace chain status

# targets (purely local convenience)
cyberspace target list
cyberspace target set 0x2b50e88 --label mytarget
cyberspace target use mytarget

# movement (local-only)
# Tip: keep comma-lists unspaced (or quote them) so negatives don’t get parsed as flags.
cyberspace move --by -1,0,0
cyberspace move --by "-1, 0, 0"

# switch planes (0=dataspace, 1=ideaspace)
cyberspace move --by 0,0,0,1

# Destination can be xyz or a 256-bit coord hex (leading zeros optional)
# Note: plane is optional; defaults to your current plane.
cyberspace move --to x,y,z
cyberspace move --to x,y,z,1
cyberspace move --to 0x2b50e88

# Move continuously toward a destination (each hop is appended immediately; Ctrl+C keeps progress)
# --toward supports a target in a different plane: it will do a final plane-switch hop when xyz matches.
# While running, it prints per-hop progress.
cyberspace move --toward 0x2b50e88

# If no destination is provided, `cyberspace move` defaults to moving `--toward` the current target.
cyberspace move

# Very large hops are rejected by default because proof computation is O(2^h)
# where h is the per-axis LCA height.
# You can override per-command:
cyberspace move --to 0x2b50e88 --max-lca-height 25

# Or persist a default so you don't need the flag every time:
cyberspace config show
cyberspace config set --max-lca-height 16

# Benchmark your machine and get a recommended default ("Optimal Speed" near ~2 seconds):
cyberspace bench

cyberspace history --limit 50
cyberspace history --json

# position utilities
cyberspace whereami
cyberspace sector

# open the built-in 3D visualizer (optional deps)
cyberspace 3d

# sector-local 3D view (renders only the current sector cube; spawn renders only if in the same sector)
cyberspace 3d --sector

# plot LCA spikes + 2^h boundaries around your current axis value (optional deps)
cyberspace lcaplot
cyberspace lcaplot --axis z --span 2048 --max-lca-height 17

cyberspace gps 37.7749,-122.4194
# or
cyberspace gps --lat 37.7749 --lon -122.4194

# cantor + encryption/debug (prints LCA heights, Cantor roots, and 1-hash/2-hash ids)
cyberspace cantor --from-xyz 0,0,0 --to-xyz 3,2,1

Optional GUI dependencies

The cyberspace 3d and cyberspace lcaplot commands require extra dependencies:

pip install 'cyberspace-cli[visualizer]'

On Linux you may also need python3-tk for Tkinter.

Local storage

• State: ~/.cyberspace/state.json
  • Includes the current coordinate and which chain is active.
• Chains: ~/.cyberspace/chains/<label>.jsonl
  • One JSON event per line.

Environment variables

• CYBERSPACE_HOME: override ~/.cyberspace
• CYBERSPACE_STATE_PATH: override the state path (useful for testing)

Tests (golden vectors)

PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'

Security

This prototype stores the private key locally in plaintext. Treat it like a hot wallet key.