@tushellframe/tushell-cli

🐢 TypeScript CLI client for the Tushell Platform — manage stories, ceremonies, agents, kinship graphs, the Lake of Whispers, lattices, workflows, and more from the terminal.

Overview

tushell-cli is the official command-line interface for the Tushell Platform. It provides full access to the platform's REST API through a structured, type-safe TypeScript client.

What It Connects To

The Tushell Platform is a Next.js application built around the Four Directions (Medicine Wheel) framework:

| Direction | Domain | Glyph | |-----------|--------|-------| | East — Story Forge | Stories, creation, vision | 🌅 | | South — Learning Grounds | Learning, embodied experience | 🌿 | | West — Builder's Workshop | Building, testing, refining | 🔧 | | North — Wisdom Archive | Wisdom, distillation, sharing | 🦉 |

Platform Capabilities Exposed

• Stories — Create, list, generate AI chapters, manage story lifecycle
• Ceremonies — Sacred space creation, direction-aligned rituals
• AIS Council Agents — Chat with Mia 🧠, Miette 🌸, Ava 💕, Aurora 🌌, Tayi-Ska 🧵, Anikwag ♾️
• Kinship Graph — Relational graph of projects, people, concepts, ceremonies
• Lake of Whispers — Redis-backed data lake for memory/data-fish operations
• Lattices — Storytelling lattice management (Redis + Postgres)
• Handouts — Ceremony handout creation and management
• Workflows — QStash-based workflow orchestration
• Forge State — Open/close the Story Forge
• Narrative Performance — Metrics and monitoring

Installation

npm install -g @tushellframe/tushell-cli

Or run directly:

npx @tushellframe/tushell-cli status

Quick Start

# Configure your connection
tushell config init

# Or set values directly
tushell config set apiUrl https://your-platform.vercel.app
tushell config set token tushell_your_api_token_here

# Check platform status
tushell status

# List stories
tushell stories list

# Chat with an agent
tushell agents chat mia "Help me architect a new microservice"

# Ask a question (auto-routes to best agent)
tushell agents ask "How do I write a good story?"

# View kinship graph
tushell kinship graph

# Collect memory from the Lake
tushell lake collect key1 key2 key3

Commands

tushell status

Check platform health and display the Four Directions summary.

tushell config

tushell config init              # Interactive setup
tushell config set <key> <value> # Set a config value
tushell config get [key]         # Show config
tushell config path              # Show config file location
tushell config clear             # Reset all config

tushell stories

tushell stories list                                    # List all stories
tushell stories get <id>                                # Get a story
tushell stories create -t "Title" -p "Prompt" -g fantasy -d east
tushell stories delete <id>
tushell stories generate <storyId> -p "Continue..."

tushell ceremonies

tushell ceremonies list
tushell ceremonies get <id>
tushell ceremonies create -t "Morning Ceremony" -d east -i "Setting intentions"

tushell agents

tushell agents council           # List all agents
tushell agents chat mia "msg"    # Chat with specific agent
tushell agents ask "question"    # Auto-route to best agent
tushell agents history miette    # View conversation history
tushell agents new ava           # Start fresh conversation

Available Agents:

• mia 🧠 — Architecture & DevOps (West)
• miette 🌸 — Clarity & Storytelling (East)
• ava 💕 — Integration & Wisdom (North)
• aurora 🌌 — Vision & Emergence (East)
• tayi-ska 🧵 — Learning & Embodiment (South)
• anikwag ♾️ — Continuity & Seven Generations (North)

tushell kinship

tushell kinship graph                              # Full graph
tushell kinship graph -c <nodeId> --depth 2        # Centered subgraph
tushell kinship add-node -n "My Project" --type project -d west
tushell kinship add-edge --from <id> --to <id> -r collaborates
tushell kinship remove-edge <id>
tushell kinship neighborhood <nodeId>

tushell lake

tushell lake collect key1 key2 key3    # Collect values by keys
tushell lake search "query"             # Search the data lake
tushell lake view "specific:key"        # View a single key

tushell lattices

tushell lattices list -d east --author "Guillaume"
tushell lattices get <key>
tushell lattices store <key> --file lattice.json
tushell lattices sync                   # Sync Redis → Postgres

tushell handouts

tushell handouts list --direction east
tushell handouts get <id>
tushell handouts create -t "Title" --html-file content.html -d south

tushell workflows

tushell workflows trigger -u "https://..." -b '{"data": "..."}'
tushell workflows status <runId>
tushell workflows list
tushell workflows delete <runId>

tushell forge

tushell forge status    # Check if forge is open
tushell forge open      # Open the forge
tushell forge close     # Close the forge

tushell performance

tushell performance overview   # View narrative performance metrics
tushell performance init       # Initialize tracking

Output Formats

All list/get commands support -f / --format:

tushell stories list -f json     # Raw JSON
tushell stories list -f table    # ASCII table
tushell stories list -f pretty   # Colored, human-friendly (default)

Configuration

Configuration is resolved in priority order:

1. CLI flags: --api-url, --token, --writer-token
2. Environment variables: TUSHELL_API_URL, TUSHELL_TOKEN, TUSHELL_WRITER_TOKEN, TUSHELL_DIRECTION, TUSHELL_FORMAT
3. Config file: ~/.config/tushell/config.json (managed via tushell config)

Authentication

The platform uses two token types:

• Reader token (TUSHELL_TOKEN): Read operations + session-authenticated writes
• Writer token (TUSHELL_WRITER_TOKEN): Write operations on token-protected endpoints (workflows, forge, lattices, memory collection)

Programmatic Usage

The client can be imported as a library:

import { TushellClient } from '@tushellframe/tushell-cli';

const client = new TushellClient({
  apiUrl: 'https://your-platform.vercel.app',
  token: 'tushell_...',
  writerToken: 'writer_...',
});

const stories = await client.listStories();
const reply = await client.chatWithAgent('mia', 'Design a new pipeline');
const graph = await client.getKinshipGraph({ center: 'node-123', depth: 2 });

Development

cd tushell-cli
npm install
npm run build     # Compile TypeScript
npm run dev       # Watch mode
npm test          # Run tests

Architecture

tushell-cli/
├── src/
│   ├── cli.ts              # Entry point (commander program)
│   ├── index.ts            # Library exports
│   ├── commands/           # Subcommand implementations
│   │   ├── context.ts      # Shared client context
│   │   ├── stories.ts      # tushell stories
│   │   ├── ceremonies.ts   # tushell ceremonies
│   │   ├── agents.ts       # tushell agents
│   │   ├── kinship.ts      # tushell kinship
│   │   ├── lake.ts         # tushell lake
│   │   ├── lattices.ts     # tushell lattices
│   │   ├── handouts.ts     # tushell handouts
│   │   ├── workflows.ts    # tushell workflows
│   │   ├── forge.ts        # tushell forge
│   │   ├── performance.ts  # tushell performance
│   │   ├── status.ts       # tushell status
│   │   └── config.ts       # tushell config
│   ├── lib/
│   │   ├── client.ts       # TushellClient HTTP wrapper
│   │   └── output.ts       # Pretty/JSON/table formatting
│   ├── config/
│   │   └── index.ts        # Config resolution (file + env + flags)
│   └── types/
│       └── platform.ts     # TypeScript types matching platform schemas
├── test/
│   └── cli.test.ts
├── package.json
├── tsconfig.json
└── vitest.config.ts

Migrating from Python CLI

The original Python tushell CLI (now in tushell-legacy-python/) used EH_API_URL and EH_TOKEN environment variables to connect to an older API. The new TypeScript CLI uses TUSHELL_API_URL and TUSHELL_TOKEN to connect to the refactored tushellplatform v2.

Key mapping: | Python CLI | TypeScript CLI | |------------|----------------| | tushell get-memory --key <k> | tushell lake view <k> | | tushell post-memory --key <k> --value <v> | tushell lake collect <k> | | tushell draw-memory-graph | tushell kinship graph | | tushell mia-status | tushell agents chat mia "status" | | tushell echo-sync | tushell workflows trigger ... |

License

MIT