@kya-os/cli/README.md

CLI for MCP-I setup and management

# @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

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

## Quick Start

```bash
# 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.

```bash
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.

```bash
mcpi check
```

Options:

- `-v, --verbose` - Show detailed information

### `env`

Manage environment variables for different deployment targets.

```bash
# 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.

```bash
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.

```bash
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.

```bash
mcpi dev
```

### `build`

Build application for production.

```bash
mcpi build
```

### `start`

Start production server.

```bash
mcpi start
```

### `register`

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

```bash
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.

```bash
mcpi status
```

Options:

- `--json` - Output in JSON format for automation

### `receipts`

List and manage stored receipts from registration and claim operations.

```bash
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.

```bash
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.

```bash
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.

```bash
# 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

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

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

### AWS Lambda

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

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

### Docker

```bash
# 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

```bash
# 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:

   ```bash
   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:
   ```bash
   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