# @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
kya-os 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
kya-os check
```

Options:

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

### `env`

Manage environment variables for different deployment targets.

```bash
# Show required environment variables
kya-os env show

# Copy environment variables to clipboard
kya-os env copy

# Verify environment variables are set correctly
kya-os env verify
```

### `rotate`

Rotate identity keys with automatic grace period handling.

```bash
kya-os 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
kya-os claim
```

### `demo`

Run interactive demos to explore KYA-OS CLI features.

```bash
# Interactive menu
kya-os demo

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

# Run init demo at increased speed
kya-os 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 `.kya-os/` directory in your project root:

```
.kya-os/
├── config.json      # Agent configuration
├── identity.json    # Identity information (DID, keys)
└── .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