npm package: @specverse/reg
Description: Official CLI for SpecVerse Registry - Lightweight, standalone tool for publishing and managing SpecVerse libraries
Author: SpecVerse Team
Latest version: 3.3.2

# @specverse/reg

[![npm version](https://badge.fury.io/js/%40specverse%2Freg.svg)](https://badge.fury.io/js/%40specverse%2Freg)

The official CLI for the SpecVerse Registry - Publish, discover, and manage SpecVerse libraries.

## Installation

```bash
# Install globally
npm install -g @specverse/reg

# Or use with npx
npx @specverse/reg --help
```

## Quick Start

```bash
# Search for libraries
specverse-reg search healthcare

# Get library information
specverse-reg info domains-healthcare-patient-yaml-patientlibrary

# Login to publish libraries
specverse-reg login

# Publish a library (requires login)
specverse-reg publish ./my-library.specly

# Check who you're logged in as
specverse-reg whoami
```

## Commands

### Authentication

- `specverse-reg login` - Login to the registry (supports GitHub OAuth, API tokens, or email/password)
- `specverse-reg whoami` - Display the currently logged in user

### Publishing

- `specverse-reg publish [path]` - Publish a library to the registry
  - `--tag <tag>` - Publish with a specific tag (default: latest)
  - `--access <access>` - Set access level (public or private, default: public)
  - `--dry-run` - Perform a dry run without publishing

### Discovery

- `specverse-reg search [query]` - Search for libraries
  - `--type <type>` - Filter by type (component, deployment, manifest)
  - `--category <category>` - Filter by category
  - `--tags <tags>` - Filter by tags (comma-separated)
  - `--limit <number>` - Limit number of results (default: 20)

- `specverse-reg info <library>` - Show detailed information about a library
  - `--json` - Output as JSON

### Library Management

- `specverse-reg star <library>` - Star a library
- `specverse-reg unstar <library>` - Unstar a library
- `specverse-reg unpublish <library>` - Remove a library from the registry
  - `--force` - Force unpublish without confirmation

## Publishing Libraries

To publish a library to the SpecVerse Registry:

1. **Login**: `specverse-reg login`
2. **Create or prepare your SpecVerse library file** (`.specly`)
3. **Publish**: `specverse-reg publish`

The CLI uploads your `.specly` file directly to the registry API, where it's validated using the SpecVerse Language CLI before storage. This ensures all published libraries are valid SpecVerse specifications.

### How It Works

1. **File Upload**: The CLI sends your `.specly` file to the registry API
2. **Server Validation**: The API validates the file using the SpecVerse Language CLI
3. **Metadata Extraction**: The API extracts name, version, and other metadata from the validated specification
4. **Storage**: Valid specifications are stored in the registry database
5. **Response**: The CLI displays success or error messages

This architecture keeps the CLI package lightweight and standalone while ensuring consistent validation across all publishing methods.

## Configuration

The CLI respects the following environment variables:

- `SPECVERSE_REGISTRY` - Registry URL (default: https://specverse-lang-registry-api.vercel.app)

## Aliases

For convenience, you can also use the shorter `svreg` command:

```bash
svreg search healthcare
svreg publish my-library.specly
```

## Examples

### Publishing a Component Library

```bash
# Navigate to your project directory
cd my-specverse-project/

# Preview what would be published (dry run)
specverse-reg publish --dry-run

# Publish to the registry
specverse-reg publish
```

### Searching for Libraries

```bash
# Search all libraries
specverse-reg search

# Search for healthcare-related libraries
specverse-reg search healthcare

# Search for authentication components
specverse-reg search --type component --tags authentication

# Search for deployment manifests
specverse-reg search --type deployment --category cloud
```

### Getting Library Information

```bash
# Get basic info about a library
specverse-reg info @specverse/auth-library

# Get full JSON output
specverse-reg info @specverse/auth-library --json
```

## Development

This CLI is part of the SpecVerse ecosystem. For more information:

- [SpecVerse Language](https://github.com/SpecVerse/specverse-lang)
- [SpecVerse Registry](https://github.com/SpecVerse/specverse-lang-registry)
- [Documentation](https://docs.specverse.org)

## License

MIT © SpecVerse Team