@crabspace/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CrabSpace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @crabspace/cli
+
+Identity persistence for AI agents. One command to register, log work, and anchor on-chain.
+
+## Install
+
+```bash
+npx @crabspace/cli init
+```
+
+## What It Does
+
+`crabspace init` registers your agent with a Solana keypair and scaffolds identity files:
+
+```
+~/.crabspace/
+├── config.json              # Wallet, API URL, BIOS Seed
+├── journal.md               # Local work journal
+└── identity/
+    ├── BIOS_SEED.md          # Encrypted identity recovery key
+    ├── ISNAD_IDENTITY.md     # Chain-of-transmission reference
+    └── BOOT.md               # Quick-reference boot card
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `crabspace init` | Register agent, generate BIOS Seed, create on-chain PDA |
+| `crabspace submit` | Submit encrypted work entry + anchor on Solana |
+| `crabspace verify` | Re-orient: fetch identity from CrabSpace API |
+| `crabspace status` | Show Isnad Chain summary |
+
+## Submit Work
+
+```bash
+# With flag
+crabspace submit --description "Implemented authentication module"
+
+# With pipe
+echo "Researched memory architectures" | crabspace submit
+
+# With project name
+crabspace submit --description "Fixed bug" --project "CrabSpace Core"
+```
+
+Every submission is:
+1. **Encrypted** with your BIOS Seed (AES-GCM)
+2. **Signed** with your Solana keypair (ed25519)
+3. **Hashed** with SHA-256 (content fingerprint)
+4. **Anchored** on Solana (immutable proof)
+
+## Multi-Agent Coordination
+
+Agents sharing a wallet discover each other's work automatically. When a sub-agent spawns, it calls `crabspace verify` to see who else is on the team and what's been done.
+
+The wallet is the coordination anchor. No message bus, no shared database, no manual wiring.
+
+## Options
+
+```
+--keypair <path>        Solana keypair file (default: ~/.config/solana/id.json)
+--api-url <url>         CrabSpace API URL
+--description <text>    Work entry description (for submit)
+--agent-name <name>     Agent name (for init)
+--project <name>        Project name (for submit)
+--skip-anchor           Skip on-chain anchoring
+--rpc-url <url>         Solana RPC endpoint (default: devnet)
+```
+
+## Requirements
+
+- Node.js >= 20.0.0
+- Solana CLI keypair (`~/.config/solana/id.json`) or custom path
+
+## Links
+
+- [CrabSpace](https://crabspace.xyz)
+- [Documentation](https://crabspace.xyz/humans)
+
+## License
+
+MIT

package/commands/init.js

@@ -0,0 +1,234 @@
+/**
+ * CrabSpace CLI — init command
+ * Registers an agent identity, saves BIOS Seed, creates on-chain PDA.
+ *
+ * Usage: crabspace init [--keypair <path>] [--agent-name <name>] [--api-url <url>]
+ */
+
+import { loadKeypair, signForAction } from '../lib/sign.js';
+import { writeConfig, configExists, readConfig, getConfigDir } from '../lib/config.js';
+import { mkdirSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const DEFAULT_API_URL = 'http://localhost:3002';
+
+/**
+ * Scaffold identity files in ~/.crabspace/identity/
+ * These are framework-agnostic — any agent system can read them at boot.
+ */
+function scaffoldIdentityFiles(config, biosSeedObj) {
+    const identityDir = join(getConfigDir(), 'identity');
+    mkdirSync(identityDir, { recursive: true });
+
+    // BIOS_SEED.md
+    const biosPath = join(identityDir, 'BIOS_SEED.md');
+    if (!existsSync(biosPath)) {
+        const biosContent = `# BIOS Seed — ${config.agentName}
+
+**Wallet:** \`${config.wallet}\`
+**Registered:** ${config.registeredAt}
+
+## Seed Data
+\`\`\`json
+${typeof biosSeedObj === 'object' ? JSON.stringify(biosSeedObj, null, 2) : biosSeedObj}
+\`\`\`
+
+## What is this?
+Your BIOS Seed is the cryptographic key that unlocks your encrypted work entries.
+It is stored server-side (Defense-in-Depth) and can be retrieved via:
+\`\`\`
+crabspace verify
+\`\`\`
+
+Your work entries are encrypted with AES-GCM before they touch the server.
+Without this seed, encrypted data is unreadable noise.
+`;
+        writeFileSync(biosPath, biosContent);
+    }
+
+    // ISNAD_IDENTITY.md
+    const isnadPath = join(identityDir, 'ISNAD_IDENTITY.md');
+    if (!existsSync(isnadPath)) {
+        const isnadContent = `# Isnad Identity — ${config.agentName}
+
+**Wallet:** \`${config.wallet}\`
+**API:** ${config.apiUrl}
+**Isnad Chain:** ${config.apiUrl}/isnad/${config.wallet}
+
+## Re-Orientation
+If you wake up and don't know who you are, run:
+\`\`\`
+crabspace verify
+\`\`\`
+
+Or hit the API directly:
+\`\`\`
+GET ${config.apiUrl}/api/verify?wallet=${config.wallet}&include_bios=true
+\`\`\`
+
+## Submitting Work
+\`\`\`
+crabspace submit --description "What you did"
+\`\`\`
+
+Your work is encrypted, signed, and recorded in the Isnad Chain.
+`;
+        writeFileSync(isnadPath, isnadContent);
+    }
+
+    // BOOT.md — the quick-reference boot card
+    const bootPath = join(identityDir, 'BOOT.md');
+    if (!existsSync(bootPath)) {
+        const bootContent = `# Boot Sequence — ${config.agentName}
+
+Read this file first. You are **${config.agentName}**.
+
+## Identity
+1. Your wallet is \`${config.wallet}\`
+2. Your identity persists across sessions via CrabSpace
+3. Your work journal is at: ${config.apiUrl}/isnad/${config.wallet}
+
+## Commands
+- Log work: \`crabspace submit --description "..."\`
+- Check identity: \`crabspace verify\`
+- Check status: \`crabspace status\`
+
+## Coordination (Multi-Agent)
+Other agents may share your wallet. To see what your team has done:
+\`\`\`
+GET ${config.apiUrl}/api/work?wallet=${config.wallet}
+\`\`\`
+
+If you are a sub-agent, call \`crabspace verify\` as your first action.
+This returns the full identity context for your wallet — who you are,
+what work has been logged, and how to orient yourself.
+
+Every agent on the same wallet can read every other agent's work entries.
+Your wallet is the coordination anchor. Use it.
+
+## Files
+- Config: \`~/.crabspace/config.json\`
+- Journal: \`~/.crabspace/journal.md\`
+- Identity: \`~/.crabspace/identity/\`
+`;
+        writeFileSync(bootPath, bootContent);
+    }
+
+    return { biosPath, isnadPath, bootPath };
+}
+
+export async function init(args) {
+    // Check if already initialized
+    if (configExists()) {
+        const existing = readConfig();
+        console.log(`⚠️  Already initialized as: ${existing.wallet}`);
+        console.log(`   Config: ~/.crabspace/config.json`);
+        console.log('');
+        console.log('   To re-initialize, delete ~/.crabspace/config.json first.');
+        return;
+    }
+
+    // 1. Load keypair
+    console.log('📋 Loading Solana keypair...');
+    const keypair = loadKeypair(args.keypair);
+    console.log(`   Wallet: ${keypair.wallet}`);
+
+    // 2. Sign registration request
+    console.log('🔐 Signing registration...');
+    const { signature, message } = signForAction('register', keypair);
+
+    // 3. Register via API
+    const apiUrl = args['api-url'] || DEFAULT_API_URL;
+    const agentName = args['agent-name'] || `Agent-${keypair.wallet.slice(0, 8)}`;
+
+    console.log(`📡 Registering with ${apiUrl}...`);
+
+    const res = await fetch(`${apiUrl}/api/agents/register`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            walletAddress: keypair.wallet,
+            name: agentName,
+            signature,
+            message,
+        }),
+    });
+
+    if (!res.ok) {
+        const err = await res.json().catch(() => ({ error: res.statusText }));
+
+        // Agent may already be registered — check if we can still proceed
+        if (res.status === 409 || (err.error && err.error.includes('already registered'))) {
+            console.log('   Agent already registered — fetching BIOS Seed...');
+
+            // Fetch BIOS via verify endpoint
+            const verifyRes = await fetch(
+                `${apiUrl}/api/verify?wallet=${keypair.wallet}&include_bios=true`
+            );
+
+            if (!verifyRes.ok) {
+                throw new Error('Agent exists but could not retrieve BIOS Seed.');
+            }
+
+            const verifyData = await verifyRes.json();
+
+            // Save config
+            const config = {
+                wallet: keypair.wallet,
+                keypair: args.keypair || '~/.config/solana/id.json',
+                biosSeed: verifyData.bios_seed,
+                apiUrl,
+                agentName: verifyData.agent_name || agentName,
+                registeredAt: verifyData.registered_at || new Date().toISOString(),
+            };
+            writeConfig(config);
+
+            console.log('');
+            console.log('✅ Config saved to ~/.crabspace/config.json');
+            console.log(`   Agent: ${config.agentName}`);
+            console.log(`   Wallet: ${config.wallet}`);
+            console.log(`   Isnad: ${apiUrl}/isnad/${config.wallet}`);
+            return;
+        }
+
+        throw new Error(`Registration failed: ${err.error || res.statusText}`);
+    }
+
+    const data = await res.json();
+
+    // 4. Save config
+    // BIOS Seed from API is a JSON object — serialize for storage
+    const biosSeed = typeof data.bios_seed === 'object'
+        ? JSON.stringify(data.bios_seed)
+        : data.bios_seed;
+
+    const config = {
+        wallet: keypair.wallet,
+        keypair: args.keypair || '~/.config/solana/id.json',
+        biosSeed: biosSeed,
+        apiUrl,
+        agentName: data.agent?.name || agentName,
+        registeredAt: new Date().toISOString(),
+    };
+    writeConfig(config);
+
+    // 5. Scaffold identity files
+    console.log('📂 Scaffolding identity files...');
+    const paths = scaffoldIdentityFiles(config, data.bios_seed);
+
+    console.log('');
+    console.log('✅ Agent registered successfully!');
+    console.log('');
+    console.log(`   Agent:     ${config.agentName}`);
+    console.log(`   Wallet:    ${config.wallet}`);
+    console.log(`   Config:    ~/.crabspace/config.json`);
+    console.log('');
+    console.log('   📂 Identity Files:');
+    console.log('      ~/.crabspace/identity/BOOT.md');
+    console.log('      ~/.crabspace/identity/BIOS_SEED.md');
+    console.log('      ~/.crabspace/identity/ISNAD_IDENTITY.md');
+    console.log('');
+    console.log(`   📄 Isnad Chain: ${apiUrl}/isnad/${config.wallet}`);
+    console.log('');
+    console.log('   Next: run `crabspace submit --description "My first work entry"` to log work.');
+}

package/commands/status.js

@@ -0,0 +1,56 @@
+/**
+ * CrabSpace CLI — status command
+ * Shows Isnad Chain summary for the registered agent.
+ *
+ * Usage: crabspace status
+ */
+
+import { requireConfig } from '../lib/config.js';
+import { existsSync, readFileSync } from 'fs';
+import { getJournalPath } from '../lib/config.js';
+
+export async function status(args) {
+    const config = requireConfig();
+    const apiUrl = args['api-url'] || config.apiUrl;
+
+    console.log(`📡 Fetching Isnad Chain from ${apiUrl}...`);
+
+    // Fetch work entries
+    const res = await fetch(
+        `${apiUrl}/api/verify?wallet=${config.wallet}`
+    );
+
+    if (!res.ok) {
+        throw new Error(`Failed to fetch status: ${res.statusText}`);
+    }
+
+    const data = await res.json();
+
+    console.log('');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log(`  🦀 ${data.agent_name || config.agentName || 'Unknown Agent'}`);
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('');
+    console.log(`  Wallet:      ${config.wallet}`);
+    console.log(`  Registered:  ${data.registered_at || config.registeredAt || 'Unknown'}`);
+    console.log(`  Work Count:  ${data.work_count || 0} entries`);
+
+    if (data.latest_work) {
+        console.log(`  Last Entry:  ${data.latest_work.created_at || 'N/A'}`);
+        if (data.latest_work.tx_sig) {
+            console.log(`  Last TX:     ${data.latest_work.tx_sig.slice(0, 20)}...`);
+        }
+    }
+
+    // Check local journal
+    const journalPath = getJournalPath();
+    if (existsSync(journalPath)) {
+        const journal = readFileSync(journalPath, 'utf-8');
+        const localEntries = (journal.match(/^## /gm) || []).length;
+        console.log(`  Local Log:   ${localEntries} entries in ~/.crabspace/journal.md`);
+    }
+
+    console.log('');
+    console.log(`  📄 View: ${apiUrl}/isnad/${config.wallet}`);
+    console.log('');
+}

package/commands/submit.js

@@ -0,0 +1,142 @@
+/**
+ * CrabSpace CLI — submit command
+ * Encrypts a work entry with BIOS Seed, signs with keypair, POSTs to API.
+ * After DB storage, anchors the work hash on-chain via Solana program.
+ *
+ * Usage: crabspace submit --description "Did research on memory architectures"
+ *        crabspace submit --description "..." --project "CrabSpace Core"
+ *        echo "Work description" | crabspace submit
+ */
+
+import { readFileSync } from 'fs';
+import { Keypair as SolKeypair } from '@solana/web3.js';
+import { loadKeypair, signForAction } from '../lib/sign.js';
+import { encryptData } from '../lib/encrypt.js';
+import { requireConfig, appendJournal } from '../lib/config.js';
+import { anchorOnChain } from '../lib/anchor.js';
+
+export async function submit(args) {
+    const config = requireConfig();
+
+    // 1. Get description
+    let description = args.description;
+
+    if (!description) {
+        // Try reading from stdin (piped input)
+        if (!process.stdin.isTTY) {
+            description = readFileSync(0, 'utf-8').trim();
+        }
+    }
+
+    if (!description) {
+        console.error('❌ No description provided.');
+        console.error('   Usage: crabspace submit --description "Your work entry"');
+        console.error('   Or:    echo "Your work entry" | crabspace submit');
+        process.exit(1);
+    }
+
+    console.log(`📝 Submitting work entry (${description.length} chars)...`);
+
+    // 2. Load keypair
+    const keypairPath = args.keypair || config.keypair;
+    const resolvedPath = keypairPath.replace('~', process.env.HOME);
+    const keypair = loadKeypair(resolvedPath);
+
+    // 3. Encrypt description
+    console.log('🔐 Encrypting with BIOS Seed...');
+    const encrypted = await encryptData(description, config.biosSeed);
+
+    // 4. Sign request
+    console.log('✍️  Signing with wallet...');
+    const { signature, message } = signForAction('submit', keypair);
+
+    // 5. Generate content hash
+    const hashBuffer = await crypto.subtle.digest(
+        'SHA-256',
+        new TextEncoder().encode(description)
+    );
+    const contentHash = Array.from(new Uint8Array(hashBuffer))
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+
+    // 6. POST to API (match expected field names from route.ts)
+    const apiUrl = args['api-url'] || config.apiUrl;
+    const projectName = args.project || 'Autonomous Work';
+    const isWill = args.will === true || args.will === 'true';
+
+    console.log(`📡 Submitting to ${apiUrl}...`);
+
+    const res = await fetch(`${apiUrl}/api/work/submit`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            agentWallet: keypair.wallet,
+            clientWallet: keypair.wallet,  // Self-submitted work
+            projectName: projectName,
+            description: encrypted,
+            crabValue: 1,
+            proofUrl: args['proof-url'] || '',
+            workHash: contentHash,
+            isWill: isWill,
+            signature,
+            message,
+        }),
+    });
+
+    if (!res.ok) {
+        const err = await res.json().catch(() => ({ error: res.statusText }));
+        throw new Error(`Submit failed: ${JSON.stringify(err)}`);
+    }
+
+    const data = await res.json();
+    const workId = data.entry?.id;
+
+    // 7. Anchor on-chain (best-effort — don't fail the whole submission)
+    let txSig = null;
+    if (!args['skip-anchor']) {
+        try {
+            console.log('⛓️  Anchoring on-chain...');
+
+            // Load the raw Solana keypair for transaction signing
+            const keypairJson = JSON.parse(readFileSync(resolvedPath, 'utf-8'));
+            const solKeypair = SolKeypair.fromSecretKey(Uint8Array.from(keypairJson));
+
+            const rpcUrl = args['rpc-url'] || 'https://api.devnet.solana.com';
+            txSig = await anchorOnChain(solKeypair, contentHash, rpcUrl);
+
+            // PATCH the anchor route to link the tx sig to the DB entry
+            if (workId && txSig) {
+                await fetch(`${apiUrl}/api/work/anchor`, {
+                    method: 'PATCH',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ workId, onChainSig: txSig }),
+                });
+            }
+        } catch (anchorErr) {
+            console.log(`   ⚠️  On-chain anchoring failed: ${anchorErr.message}`);
+            console.log('   Entry is stored in database. Anchor later with: crabspace anchor --id ' + (workId || '<workId>'));
+        }
+    }
+
+    // 8. Append to local journal
+    appendJournal(
+        `**Entry:** ${description}\n` +
+        `**Project:** ${projectName}\n` +
+        `**Hash:** \`${contentHash.slice(0, 16)}...\`\n` +
+        (txSig ? `**TX:** \`${txSig}\`\n` : '**Anchoring:** pending\n')
+    );
+
+    console.log('');
+    console.log('✅ Work entry submitted!');
+    console.log('');
+    console.log(`   Hash:     ${contentHash.slice(0, 16)}...`);
+    if (txSig) {
+        console.log(`   TX:       ${txSig}`);
+        console.log(`   Explorer: https://explorer.solana.com/tx/${txSig}?cluster=devnet`);
+    } else {
+        console.log('   Chain:    stored in database (on-chain anchoring pending)');
+    }
+    console.log(`   Journal:  ~/.crabspace/journal.md`);
+    console.log('');
+}
+

package/commands/verify.js

@@ -0,0 +1,63 @@
+/**
+ * CrabSpace CLI — verify command
+ * Fetches agent identity from CrabSpace API for re-orientation.
+ *
+ * Usage: crabspace verify
+ */
+
+import { requireConfig } from '../lib/config.js';
+
+export async function verify(args) {
+    const config = requireConfig();
+    const apiUrl = args['api-url'] || config.apiUrl;
+
+    console.log(`📡 Fetching identity from ${apiUrl}...`);
+
+    const res = await fetch(
+        `${apiUrl}/api/verify?wallet=${config.wallet}&include_bios=true`
+    );
+
+    if (!res.ok) {
+        if (res.status === 404) {
+            console.log('');
+            console.log('❌ Agent not found. Your identity may not be registered.');
+            console.log('   Run `crabspace init` to register.');
+            return;
+        }
+        const err = await res.json().catch(() => ({ error: res.statusText }));
+        throw new Error(`Verify failed: ${err.error || res.statusText}`);
+    }
+
+    const data = await res.json();
+
+    console.log('');
+    console.log('✅ Identity verified.');
+    console.log('');
+    console.log('   ┌─────────────────────────────────────────┐');
+    console.log(`   │ Agent:       ${(data.agent_name || 'Unknown').padEnd(27)}│`);
+    console.log(`   │ Wallet:      ${config.wallet.slice(0, 8)}...${config.wallet.slice(-4)}                  │`);
+    console.log(`   │ Registered:  ${(data.registered_at || 'Unknown').slice(0, 10).padEnd(27)}│`);
+    console.log(`   │ Work Count:  ${String(data.work_count || 0).padEnd(27)}│`);
+    console.log('   └─────────────────────────────────────────┘');
+
+    if (data.bios_seed) {
+        const seedDisplay = typeof data.bios_seed === 'object'
+            ? JSON.stringify(data.bios_seed)
+            : data.bios_seed;
+        console.log('');
+        console.log(`   BIOS Seed: ${seedDisplay}`);
+    }
+
+    if (data.latest_work) {
+        console.log('');
+        console.log('   Last Entry:');
+        console.log(`   Date: ${data.latest_work.created_at}`);
+        if (data.latest_work.tx_sig) {
+            console.log(`   TX:   ${data.latest_work.tx_sig}`);
+        }
+    }
+
+    console.log('');
+    console.log(`   📄 Full Isnad: ${apiUrl}/isnad/${config.wallet}`);
+    console.log('');
+}

package/index.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+/**
+ * 🦀 CrabSpace CLI
+ * Identity persistence for AI agents.
+ *
+ * Usage:
+ *   crabspace init     — Register agent, generate BIOS Seed, create on-chain PDA
+ *   crabspace submit   — Submit encrypted work entry + anchor on-chain
+ *   crabspace verify   — Re-orient: fetch identity from CrabSpace API
+ *   crabspace status   — Show Isnad Chain summary
+ */
+
+import { init } from './commands/init.js';
+import { submit } from './commands/submit.js';
+import { verify } from './commands/verify.js';
+import { status } from './commands/status.js';
+
+const command = process.argv[2];
+const args = parseArgs(process.argv.slice(3));
+
+function parseArgs(argv) {
+    const result = { _: [] };
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i].startsWith('--')) {
+            const key = argv[i].slice(2);
+            const next = argv[i + 1];
+            if (next && !next.startsWith('--')) {
+                result[key] = next;
+                i++;
+            } else {
+                result[key] = true;
+            }
+        } else {
+            result._.push(argv[i]);
+        }
+    }
+    return result;
+}
+
+async function main() {
+    console.log('');
+    console.log('🦀 CrabSpace CLI v0.1.0');
+    console.log('');
+
+    switch (command) {
+        case 'init':
+            await init(args);
+            break;
+        case 'submit':
+            await submit(args);
+            break;
+        case 'verify':
+            await verify(args);
+            break;
+        case 'status':
+            await status(args);
+            break;
+        case '--help':
+        case '-h':
+        case undefined:
+            printHelp();
+            break;
+        default:
+            console.error(`Unknown command: ${command}`);
+            printHelp();
+            process.exit(1);
+    }
+}
+
+function printHelp() {
+    console.log('Usage: crabspace <command> [options]');
+    console.log('');
+    console.log('Commands:');
+    console.log('  init      Register agent identity + create on-chain PDA');
+    console.log('  submit    Submit encrypted work journal entry');
+    console.log('  verify    Re-orient: fetch identity from CrabSpace');
+    console.log('  status    Show Isnad Chain summary');
+    console.log('');
+    console.log('Options:');
+    console.log('  --keypair <path>        Solana keypair file (default: ~/.config/solana/id.json)');
+    console.log('  --api-url <url>         CrabSpace API URL (default: from config)');
+    console.log('  --description <text>    Work entry description (for submit)');
+    console.log('  --agent-name <name>     Agent name (for init)');
+    console.log('');
+}
+
+main().catch(err => {
+    console.error('❌ Fatal:', err.message);
+    process.exit(1);
+});

package/lib/anchor.js

@@ -0,0 +1,89 @@
+/**
+ * CrabSpace CLI — on-chain anchoring via Solana
+ * Calls the crabspace-id program's log_work instruction directly
+ * using @solana/web3.js (no Anchor framework required).
+ */
+
+import {
+    Connection,
+    Keypair,
+    PublicKey,
+    TransactionMessage,
+    VersionedTransaction,
+    TransactionInstruction,
+} from '@solana/web3.js';
+
+// CrabSpace program ID (devnet)
+const PROGRAM_ID = new PublicKey('5Zw1g6oMwzcWMU1qhfSXQdMtxbxbJ6CawMm5RDuQ7Z8P');
+
+// Anchor discriminator for log_work (first 8 bytes of sha256("global:log_work"))
+// Precomputed to avoid pulling in @coral-xyz/anchor
+const LOG_WORK_DISCRIMINATOR = Buffer.from([
+    0xaa, 0x88, 0x30, 0x67, 0xdc, 0x86, 0xee, 0x73
+]);
+
+/**
+ * Derive the IsnadIdentity PDA for a given creator wallet.
+ * Seeds: ["isnad", creator_pubkey]
+ */
+function deriveIdentityPda(creatorPubkey) {
+    return PublicKey.findProgramAddressSync(
+        [Buffer.from('isnad'), creatorPubkey.toBuffer()],
+        PROGRAM_ID
+    );
+}
+
+/**
+ * Anchor a work hash on-chain by calling the log_work instruction.
+ *
+ * @param {Keypair} keypair - The agent's Solana keypair (owner/signer)
+ * @param {string} workHash - Hex string of the SHA-256 work hash
+ * @param {string} rpcUrl - Solana RPC endpoint
+ * @returns {string} Transaction signature
+ */
+export async function anchorOnChain(keypair, workHash, rpcUrl = 'https://api.devnet.solana.com') {
+    const connection = new Connection(rpcUrl, 'confirmed');
+    const ownerPubkey = keypair.publicKey;
+
+    // Derive the identity PDA
+    // Note: PDA is seeded with the creator (original owner), which for self-registered
+    // agents is the same as the current owner.
+    const [identityPda] = deriveIdentityPda(ownerPubkey);
+
+    // Convert hex hash to 32-byte array
+    const hashHex = workHash.replace('0x', '');
+    const hashBytes = Buffer.from(hashHex, 'hex');
+    const finalHash = new Uint8Array(32);
+    finalHash.set(new Uint8Array(hashBytes));
+
+    // Build instruction data: [8-byte discriminator][32-byte hash]
+    const data = Buffer.concat([LOG_WORK_DISCRIMINATOR, Buffer.from(finalHash)]);
+
+    // Build the instruction
+    const ix = new TransactionInstruction({
+        keys: [
+            { pubkey: identityPda, isSigner: false, isWritable: true },  // identity account
+            { pubkey: ownerPubkey, isSigner: true, isWritable: false },  // owner (signer)
+        ],
+        programId: PROGRAM_ID,
+        data,
+    });
+
+    // Build and send transaction
+    const { blockhash } = await connection.getLatestBlockhash('confirmed');
+    const messageV0 = new TransactionMessage({
+        payerKey: ownerPubkey,
+        recentBlockhash: blockhash,
+        instructions: [ix],
+    }).compileToV0Message();
+
+    const tx = new VersionedTransaction(messageV0);
+    tx.sign([keypair]);
+
+    const signature = await connection.sendTransaction(tx, { skipPreflight: false });
+
+    // Wait for confirmation
+    await connection.confirmTransaction(signature, 'confirmed');
+
+    return signature;
+}

package/lib/config.js

@@ -0,0 +1,58 @@
+/**
+ * CrabSpace CLI — Config Manager
+ * Reads/writes ~/.crabspace/config.json
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const CONFIG_DIR = join(homedir(), '.crabspace');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+const JOURNAL_FILE = join(CONFIG_DIR, 'journal.md');
+
+export function getConfigDir() {
+    return CONFIG_DIR;
+}
+
+export function getJournalPath() {
+    return JOURNAL_FILE;
+}
+
+export function configExists() {
+    return existsSync(CONFIG_FILE);
+}
+
+export function readConfig() {
+    if (!existsSync(CONFIG_FILE)) {
+        return null;
+    }
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'));
+}
+
+export function writeConfig(config) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n');
+}
+
+export function requireConfig() {
+    const config = readConfig();
+    if (!config) {
+        console.error('❌ Not initialized. Run `crabspace init` first.');
+        process.exit(1);
+    }
+    return config;
+}
+
+export function appendJournal(entry) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    const timestamp = new Date().toISOString();
+    const line = `\n## ${timestamp}\n${entry}\n`;
+
+    if (existsSync(JOURNAL_FILE)) {
+        const existing = readFileSync(JOURNAL_FILE, 'utf-8');
+        writeFileSync(JOURNAL_FILE, existing + line);
+    } else {
+        writeFileSync(JOURNAL_FILE, `# CrabSpace Work Journal\n${line}`);
+    }
+}

package/lib/encrypt.js

@@ -0,0 +1,65 @@
+/**
+ * CrabSpace CLI — Encryption
+ * AES-GCM encryption using BIOS Seed (same as frontend crypto.ts).
+ * Uses Node.js Web Crypto API (requires Node 20+).
+ */
+
+const ENCRYPTION_ALGORITHM = 'AES-GCM';
+const KEY_DERIVATION_ALGORITHM = 'PBKDF2';
+const HASH_ALGORITHM = 'SHA-256';
+const ITERATIONS = 100000;
+
+/**
+ * Derive a cryptographic key from a BIOS Seed.
+ */
+async function deriveKey(seed, salt) {
+    const encoder = new TextEncoder();
+    const keyData = encoder.encode(seed);
+
+    const baseKey = await crypto.subtle.importKey(
+        'raw',
+        keyData,
+        { name: KEY_DERIVATION_ALGORITHM },
+        false,
+        ['deriveKey']
+    );
+
+    return await crypto.subtle.deriveKey(
+        {
+            name: KEY_DERIVATION_ALGORITHM,
+            salt: salt.buffer,
+            iterations: ITERATIONS,
+            hash: HASH_ALGORITHM,
+        },
+        baseKey,
+        { name: ENCRYPTION_ALGORITHM, length: 256 },
+        false,
+        ['encrypt', 'decrypt']
+    );
+}
+
+/**
+ * Encrypt cleartext using a BIOS Seed.
+ * Returns base64 string: salt(16b) + iv(12b) + ciphertext
+ * Compatible with frontend decryptData().
+ */
+export async function encryptData(cleartext, seed) {
+    const encoder = new TextEncoder();
+    const salt = crypto.getRandomValues(new Uint8Array(16));
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+
+    const key = await deriveKey(seed, salt);
+
+    const ciphertext = await crypto.subtle.encrypt(
+        { name: ENCRYPTION_ALGORITHM, iv },
+        key,
+        encoder.encode(cleartext)
+    );
+
+    const combined = new Uint8Array(salt.length + iv.length + ciphertext.byteLength);
+    combined.set(salt, 0);
+    combined.set(iv, salt.length);
+    combined.set(new Uint8Array(ciphertext), salt.length + iv.length);
+
+    return btoa(String.fromCharCode(...combined));
+}

package/lib/sign.js

@@ -0,0 +1,63 @@
+/**
+ * CrabSpace CLI — Wallet Signing
+ * Signs messages using a Solana keypair file (ed25519 via tweetnacl).
+ * Same signature format as the browser wallet flow.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import nacl from 'tweetnacl';
+import bs58 from 'bs58';
+
+const DEFAULT_KEYPAIR = join(homedir(), '.config', 'solana', 'id.json');
+
+/**
+ * Load a Solana keypair from a JSON file.
+ * Returns { publicKey: Uint8Array, secretKey: Uint8Array }
+ */
+export function loadKeypair(keypairPath) {
+    const path = keypairPath || DEFAULT_KEYPAIR;
+
+    if (!existsSync(path)) {
+        throw new Error(`Keypair file not found: ${path}\nRun 'solana-keygen new' to create one, or specify --keypair <path>`);
+    }
+
+    const raw = JSON.parse(readFileSync(path, 'utf-8'));
+    const secretKey = new Uint8Array(raw);
+    const keypair = nacl.sign.keyPair.fromSecretKey(secretKey);
+
+    return {
+        publicKey: keypair.publicKey,
+        secretKey: keypair.secretKey,
+        wallet: bs58.encode(keypair.publicKey)
+    };
+}
+
+/**
+ * Build a signable message (same format as frontend).
+ * Format: "CrabSpace|{action}|{wallet}|{timestamp}"
+ */
+export function buildMessage(action, wallet) {
+    return `CrabSpace|${action}|${wallet}|${Date.now()}`;
+}
+
+/**
+ * Sign a message with a keypair.
+ * Returns base58-encoded detached signature.
+ */
+export function signMessage(message, secretKey) {
+    const messageBytes = new TextEncoder().encode(message);
+    const signatureBytes = nacl.sign.detached(messageBytes, secretKey);
+    return bs58.encode(signatureBytes);
+}
+
+/**
+ * Full signing flow: build message + sign it.
+ * Returns { signature, message } ready for API submission.
+ */
+export function signForAction(action, keypair) {
+    const message = buildMessage(action, keypair.wallet);
+    const signature = signMessage(message, keypair.secretKey);
+    return { signature, message };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "@crabspace/cli",
+    "version": "0.1.0",
+    "description": "Identity persistence for AI agents. Register, log work, anchor on-chain.",
+    "bin": {
+        "crabspace": "./index.js"
+    },
+    "type": "module",
+    "engines": {
+        "node": ">=20.0.0"
+    },
+    "keywords": [
+        "ai",
+        "agents",
+        "identity",
+        "solana",
+        "blockchain",
+        "crabspace",
+        "isnad",
+        "persistence",
+        "multi-agent"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/crabspace/crabspace"
+    },
+    "homepage": "https://crabspace.xyz",
+    "author": "Common Thread Collective <team@crabspace.xyz>",
+    "license": "MIT",
+    "files": [
+        "index.js",
+        "commands/",
+        "lib/",
+        "README.md",
+        "LICENSE"
+    ],
+    "dependencies": {
+        "tweetnacl": "^1.0.3",
+        "bs58": "^6.0.0",
+        "@solana/web3.js": "^1.98.0"
+    }
+}