@kya-os/cli

Command-line interface for KYA-OS MCP-I setup and management. Claim a decentralized and unique to the internet, Agent identity as well as automatically register your MCP Server on popular directories.

Installation

npm install -g @kya-os/cli
# or use directly with npx
npx @kya-os/cli init

Quick Start

# Initialize KYA-OS in your project
npx @kya-os/cli init

# Check your setup status
npx @kya-os/cli check

# See the full CLI experience demo
npx @kya-os/cli demo

Features

• 🚀 Zero-config setup - Auto-detects your project type (Next.js, Node.js, etc.)
• 🎨 Beautiful animations - Terminal effects for key operations
• 🔐 Secure by default - Encrypted key storage, automatic rotation support
• 🌐 Platform agnostic - Works with Vercel, AWS, Docker, and more
• ⚡ Developer friendly - Clear error messages, helpful suggestions

Commands

init

Initialize MCP-I in your project with an interactive setup wizard.

mcpi init

Options:

• -n, --name <name> - Agent name
• -d, --description <description> - Agent description
• -r, --repository <url> - Repository URL
• -p, --platform <platform> - Target platform (auto-detected if not specified)
• --skip-registration - Skip agent registration (create files only)
• --force - Overwrite existing configuration

check

Check MCP-I setup status and verify configuration.

mcpi check

Options:

• -v, --verbose - Show detailed information

env

Manage environment variables for different deployment targets.

# Show required environment variables
mcpi env show

# Copy environment variables to clipboard
mcpi env copy

# Verify environment variables are set correctly
mcpi env verify

rotate

Rotate identity keys with automatic grace period handling.

mcpi keys rotate

Options:

• -f, --force - Force rotation without confirmation
• -r, --reason <reason> - Reason for rotation

claim

Get agent claim/edit URLs for the KYA-OS directory.

mcpi claim [token]

Options:

• --json - Output in JSON format for automation
• --no-save-receipt - Don't save receipt to disk
• --receipt-path <path> - Custom path for receipt storage

dev

Start development server with hot reloading.

mcpi dev

build

Build application for production.

mcpi build

start

Start production server.

mcpi start

register

Register agent with Know-That-AI (KTA) registry.

mcpi register

Options:

• --json - Output in JSON format for automation
• --no-save-receipt - Don't save receipt to disk
• --receipt-path <path> - Custom path for receipt storage

status

Show agent status including DID, key ID, KTA URL, and mirror status.

mcpi status

Options:

• --json - Output in JSON format for automation

receipts

List and manage stored receipts from registration and claim operations.

mcpi receipts

Options:

• --json - Output in JSON format for automation
• --path <path> - Custom path for receipt storage
• --verify - Verify receipts against KTA log

doctor

Check system health and compatibility.

mcpi doctor

Options:

• --json - Output in JSON format for automation
• -v, --verbose - Show detailed diagnostic information

verify

Verify proofs and signatures locally without KTA calls.

mcpi verify --local

Options:

• --local - Perform offline verification
• --json - Output in JSON format for automation
• -v, --verbose - Show detailed verification information
• --proof <path> - Path to proof file or JSON string
• --request <path> - Path to request file or JSON string
• --response <path> - Path to response file or JSON string

demo

Run interactive demos to explore KYA-OS CLI features.

# Interactive menu
mcpi demo

# Run specific demos directly
mcpi demo --init      # Full init experience
mcpi demo --ui        # UI components showcase
mcpi demo --effects   # Terminal effects showcase
mcpi demo --security  # Security scenarios

# Run init demo at increased speed
mcpi demo --init --fast

Available demos:

• 🚀 Init Experience - See the full init command flow with blackhole animation
• 🎨 UI Components - Explore tables, boxes, and gradient effects
• ✨ Terminal Effects - Watch all animation effects
• 🔑 Security Scenarios - Key deletion and identity creation

Terminal Effects

The CLI includes several stunning terminal effects:

• 🔥 Burn - Text burns away dramatically
• ✨ Beams - Light beams illuminate the text
• 💻 Binary Path - Matrix-style binary rain reveals text
• 🔓 Decrypt - Movie-style decryption animation
• 🌌 Blackhole - Text gets sucked into a void
• 🌊 Waves - Wave patterns flow across text

Effects automatically disable in CI/CD environments or when KYA_EFFECTS_ENABLED=false.

Environment Variables

The CLI respects the following environment variables:

• KYA_API_URL - KYA-OS API endpoint (default: https://api.knowthat.ai)
• KYA_API_KEY - API key for authentication
• KYA_ENV - Environment (development/staging/production)
• KYA_EFFECTS_ENABLED - Enable/disable terminal effects (default: true)
• NO_COLOR - Disable all colors (respects NO_COLOR standard)

Configuration

The CLI stores configuration in .mcpi/ directory in your project root:

.mcpi/
├── config.json      # Agent configuration
├── identity.json    # Identity information (DID, keys)
├── receipts/        # Registration and claim receipts
└── .gitignore      # Ensures secrets aren't committed

Platform-Specific Guides

Vercel

# Initialize with Vercel auto-detection
npx @kya-os/cli init

# Copy environment variables for Vercel dashboard
npx @kya-os/cli env copy

AWS Lambda

# Initialize for AWS
npx @kya-os/cli init --platform aws

# Generate CloudFormation template
npx @kya-os/cli env show --format cloudformation

Docker

# Initialize for Docker
npx @kya-os/cli init --platform docker

# Generate docker-compose.yml snippet
npx @kya-os/cli env show --format docker-compose

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run demos
npm run demo              # Interactive menu
npm run demo:init         # Init experience
npm run demo:ui           # UI components
npm run demo:effects      # Terminal effects
npm run demo:security     # Security scenarios
npm run demo:fast         # Fast init demo

Creating New Effects

1. Copy the effect template:

   cp src/effects/template/effect-template.ts src/effects/implementations/my-effect.ts

2. Implement your effect logic

3. Register in src/effects/index.ts

4. Test with:

   npm run dev:effects -- --effect my-effect --text "Test"

See src/effects/template/README.md for detailed instructions.

Troubleshooting

Effects not showing

• Check if running in TTY: test -t 1 && echo "TTY available"
• Ensure KYA_EFFECTS_ENABLED is not set to false
• Try running with --disable flag to confirm it works without effects

Module not found errors

• Run npm run build to ensure all files are compiled
• Check that you're using Node.js 16+ with ESM support

Permission denied

• On macOS/Linux: Use sudo npm install -g @kya-os/cli
• Or use npx: npx @kya-os/cli (no installation needed)

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-effect)
3. Commit your changes (git commit -m 'Add amazing effect')
4. Push to the branch (git push origin feature/amazing-effect)
5. Open a Pull Request

License

MIT