npm package: @raketa-cloud/cli
Description: Collection of useful CLI tools for humans and coding agents. 
Author: Vestimir Markov
Latest version: 1.2.2

# Raketa CLI

A collection of useful CLI tools for humans and coding agents.

## Overview

Raketa CLI is a command-line toolkit designed to streamline the creation and management of three key artifact types in your projects:

- **Widgets** - React UI components
- **Skills** - Claude AI agent capabilities and prompts
- **Commands** - Custom CLI commands

## Exploring Available Commands

To see all available commands and options:

```bash
npx @raketa-cloud/cli --help
```

To get detailed help for a specific command:

```bash
npx @raketa-cloud/cli widgets --help
npx @raketa-cloud/cli skills --help
npx @raketa-cloud/cli commands --help
```

Each command namespace has multiple sub-commands. Use the `--help` flag to discover what's available and explore the full capabilities of the tool.

## Usage Examples

### Working with Widgets

List all widgets in your project:

```bash
npx @raketa-cloud/cli widgets list
```

Create a new widget:

```bash
npx @raketa-cloud/cli widgets new --name MyWidget
```

### Working with Skills

List all skills (local and global):

```bash
npx @raketa-cloud/cli skills list-all
```

View available skills from the remote repository:

```bash
npx @raketa-cloud/cli skills list-remote
```

Install a skill locally to your project:

```bash
npx @raketa-cloud/cli skills install my-skill-name
```

Install a skill globally for system-wide use:

```bash
npx @raketa-cloud/cli skills install-global my-skill-name
```

Create a new custom skill:

```bash
npx @raketa-cloud/cli skills new --name my-custom-skill
```

### Working with Commands

List all custom commands:

```bash
npx @raketa-cloud/cli commands list
```

Create a new command:

```bash
npx @raketa-cloud/cli commands new --name "namespace.command"
```

## Local Development

If you want to develop or contribute to Raketa CLI itself, follow these steps:

### Setup

1. Clone the repository and navigate to the project directory:

```bash
git clone <repository-url>
cd raketa-cli
```

2. Install dependencies:

```bash
npm install
```

3. Link the package globally to use your local version:

```bash
npm link
```

After running `npm link`, the `raketa-cli` command will use your local development version instead of the published package. Any changes you make to the source code will be immediately available.

### Testing Your Changes

Run commands directly to test your changes:

```bash
raketa-cli widgets list
raketa-cli skills --help
```

### Cleanup

When you're done developing, unlink the package:

```bash
npm unlink -g @raketa-cloud/cli
```

This removes the global symlink and restores the default behavior.

## Project Structure

The CLI is built using Commander.js and follows a modular command structure:

- `src/commands/` - Command implementations organized by namespace
- `src/index.js` - Main entry point and command registration
- Each command extends a base `Command` class for consistency

## Contributing

Contributions are welcome! Please follow the existing patterns when adding new commands or features.

## Release Process

This project uses automated NPM publishing via GitHub Actions.

### Publishing a New Version

1. **Bump the version** using npm version command:

```bash
# For a patch release (bug fixes): 1.1.0 → 1.1.1
npm version patch

# For a minor release (new features): 1.1.0 → 1.2.0
npm version minor

# For a major release (breaking changes): 1.1.0 → 2.0.0
npm version major
```

This command automatically:
- Updates `package.json` and `package-lock.json`
- Creates a git commit with the version change
- Creates a git tag (e.g., `v1.2.0`)

2. **Push the changes and tags to GitHub:**

```bash
git push origin main
git push origin --tags
```

3. **Automated publishing:**

The GitHub Action workflow automatically:
- Validates that the package.json version matches the git tag
- Installs dependencies
- Publishes the package to NPM with public access
- Creates a GitHub release with auto-generated release notes

4. **Verify the release:**

```bash
npm view @raketa-cloud/cli
```

Visit https://www.npmjs.com/package/@raketa-cloud/cli to see the published package.

### Requirements

- The GitHub repository must have an `NPM_TOKEN` secret configured in Settings → Secrets and variables → Actions
- The NPM token should be an "Automation" type token with publish permissions for the @raketa-cloud scope

### Troubleshooting

**Version mismatch error:**
Ensure the version in `package.json` matches the git tag (without the 'v' prefix).

**NPM authentication error:**
Verify that the `NPM_TOKEN` secret is properly configured in the GitHub repository settings and has the correct permissions.

**Package already published:**
You cannot republish the same version. Bump the version and create a new release.

## License

See LICENSE file for details.