@calimero-network/registry-cli 1.15.6 → 1.17.0

package/README.md

@@ -1,699 +1,132 @@
-# Calimero Network App Registry CLI
+# calimero-registry
 
-A command-line interface tool for the Calimero Network App Registry. Provides easy-to-use commands for managing applications, developers, and attestations directly from the terminal.
+Command-line access to the Calimero App Registry: organizations, bundle metadata, and a local registry for development.
 
-## 🚀 Features
+> **Building and publishing bundles is not this tool's job.** Use [`cargo mero`](https://github.com/calimero-network/core/tree/master/tools/cargo-mero) - `cargo mero bundle` to build and sign, `cargo mero publish` to upload. See [PUBLISHING.md](../../PUBLISHING.md).
 
-- **Interactive Commands**: User-friendly interactive prompts
-- **JSON Output**: Structured JSON output for scripting
-- **Table Format**: Human-readable table output
-- **Color-coded Output**: Syntax highlighting and status indicators
-- **Auto-completion**: Command and option auto-completion
-- **Configuration Management**: Persistent configuration storage
-- **Batch Operations**: Support for bulk operations
-- **Progress Indicators**: Visual progress bars for long operations
-- **🆕 Local Registry**: Complete local development environment with file-based storage and artifact serving
-
-## 📦 Installation
-
-### Global Installation
+## Install
 
 ```bash
-# Install globally from npm
 npm install -g @calimero-network/registry-cli
-
-# Or using pnpm
-pnpm add -g @calimero-network/registry-cli
-
-# Or using yarn
-yarn global add @calimero-network/registry-cli
+# or: pnpm add -g @calimero-network/registry-cli
 ```
 
-### Local Development
+From a clone:
 
 ```bash
-# Clone the repository
-git clone https://github.com/calimero-network/app-registry.git
-cd app-registry/packages/cli
-
-# Install dependencies
-pnpm install
-
-# Build the CLI
-pnpm build
-
-# Link locally for development
-pnpm link
+pnpm install && pnpm build && pnpm link
 ```
 
-## 🔧 Configuration
+## Configuration
 
-### Initial Setup
+Two settings, resolved in this order: command flags, then environment, then the config file at `~/.calimero-registry/remote-config.json`, then the public registry.
 
 ```bash
-# Configure the CLI
-calimero-registry config set api-url https://api.calimero.network
-calimero-registry config set api-key your-api-key
-
-# View current configuration
+calimero-registry config set registry-url https://apps.calimero.network
+calimero-registry config set api-key <token>
 calimero-registry config list
+calimero-registry config get registry-url
+calimero-registry config reset [--force]
 ```
 
-### Configuration Options
-
-```bash
-# Set API URL
-calimero-registry config set api-url https://your-api-url.com
-
-# Set API key for authentication
-calimero-registry config set api-key your-api-key
-
-# Set output format (json, table, yaml)
-calimero-registry config set output-format json
-
-# Set default limit for list commands
-calimero-registry config set default-limit 20
-
-# Enable/disable color output
-calimero-registry config set color-output true
-```
-
-## 🏠 Local Registry for Development
-
-The CLI now includes a complete local registry for development purposes. This allows you to test app submissions, manage applications, and serve artifacts locally without requiring a remote registry server.
-
-### Quick Start with Local Registry
-
-```bash
-# Start local registry
-calimero-registry local start
-
-# Use local registry with existing commands
-calimero-registry apps list --local
-calimero-registry apps submit manifest.json --local
-calimero-registry health --local
-
-# Stop local registry
-calimero-registry local stop
-```
-
-### Local Registry Management
-
-```bash
-# Check status
-calimero-registry local status
-
-# Seed with sample data
-calimero-registry local seed
-
-# Reset all data
-calimero-registry local reset --force
-
-# Backup data
-calimero-registry local backup
-
-# Restore from backup
-calimero-registry local restore backup.json
-```
-
-### Key Benefits
-
-- **🔄 Offline Development**: Work without internet connection
-- **⚡ Fast Iteration**: No network delays
-- **📁 File-Based Storage**: No database required
-- **🔧 Local Artifacts**: Serve files locally instead of IPFS
-- **🛡️ Data Isolation**: Safe development without affecting production
-- **👥 Team Collaboration**: Share local registry configurations
-
-### Local vs Remote Registry
-
-| Feature      | Remote Registry | Local Registry |
-| ------------ | --------------- | -------------- |
-| Storage      | Database        | JSON Files     |
-| Artifacts    | IPFS            | Local Files    |
-| Network      | Required        | Offline        |
-| Setup        | Complex         | Simple         |
-| Data Control | Limited         | Full Control   |
-
-For detailed local registry documentation, see [LOCAL_REGISTRY.md](./LOCAL_REGISTRY.md).
-
-## 📚 Command Reference
-
-### Applications
-
-#### List Applications
-
-```bash
-# List all applications
-calimero-registry apps list
-
-# List with filters
-calimero-registry apps list --search wallet --verified --limit 10
-
-# Output in JSON format
-calimero-registry apps list --output json
-
-# Show specific fields
-calimero-registry apps list --fields name,version,developer
-
-# Use local registry
-calimero-registry apps list --local
-```
-
-#### Get Application Details
-
-```bash
-# Get application by ID
-calimero-registry apps get app-id
-
-# Get with full details
-calimero-registry apps get app-id --full
-
-# Get manifest only
-calimero-registry apps get app-id --manifest
-```
-
-#### Create Application
+| Key            | Environment             | Default                         |
+| -------------- | ----------------------- | ------------------------------- |
+| `registry-url` | `CALIMERO_REGISTRY_URL` | `https://apps.calimero.network` |
+| `api-key`      | `CALIMERO_API_KEY`      | none                            |
 
-```bash
-# Interactive creation
-calimero-registry apps create
+`registry-url` and `api-key` are the only keys. Get a token from the registry's Organizations page, under **CLI Access**; `cargo mero` reads the same two variables.
 
-# Create from file
-calimero-registry apps create --file app-manifest.json
-
-# Create with inline data
-calimero-registry apps create \
-  --name "My self-sovereign application" \
-  --description "A smart contract application" \
-  --version "1.0.0" \
-  --developer-id "developer-id"
-
-# Submit to local registry
-calimero-registry apps submit manifest.json --local
-```
+## Organizations
 
-#### Update Application
+The main reason to use this CLI. Every write needs an API token; `org get` and `org members list` are public.
 
 ```bash
-# Update application
-calimero-registry apps update app-id --description "Updated description"
+calimero-registry org list                                  # resolves your email from the token
+calimero-registry org create -n "My Org" -s "my-org"        # both flags required
+calimero-registry org get    <orgId>                        # id or slug
+calimero-registry org update <orgId> [-n <name>] [-m <json>]
+calimero-registry org delete <orgId> [-y]                   # irreversible
 
-# Update from file
-calimero-registry apps update app-id --file updates.json
+calimero-registry org members list   <orgId>
+calimero-registry org members add    <orgId> <email> [-r admin|member]
+calimero-registry org members update <orgId> <email> -r admin|member
+calimero-registry org members remove <orgId> <email>
 
-# Update version
-calimero-registry apps update app-id --version "1.1.0"
+calimero-registry org packages link   <orgId> <package>
+calimero-registry org packages unlink <orgId> <package>
 ```
 
-#### Delete Application
-
-```bash
-# Delete application
-calimero-registry apps delete app-id
-
-# Force delete (skip confirmation)
-calimero-registry apps delete app-id --force
-```
-
-### Developers
-
-#### List Developers
+Members are identified by email, so removing someone takes effect on their next request with no key rotation involved. Linking a package to an org lets any member publish new versions of it **through the browser upload**; a `cargo mero publish` still has to be signed by the key that owns the package. See the [ownership rules](../../README.md#ownership-and-publishing-rights).
 
-```bash
-# List all developers
-calimero-registry developers list
-
-# List with filters
-calimero-registry developers list --search john --verified
-
-# Show developer apps
-calimero-registry developers list --include-apps
-```
-
-#### Get Developer Details
+## Bundles
 
 ```bash
-# Get developer by ID
-calimero-registry developers get developer-id
+# edit published metadata: fetch with changes applied, sign, then PATCH back
+calimero-registry bundle edit <package> <version> --remote \
+  [--name <name>] [--description <text>] [--author <author>] \
+  [--frontend <url>] [--github <url>] [--docs <url>] \
+  [-o <path>]            # where to write the manifest to sign (default manifest.json)
+  [--manifest <path>]    # PATCH this already-signed manifest instead
+  [--url <registry-url>] [--api-key <key>]
 
-# Get with apps
-calimero-registry developers get developer-id --include-apps
-```
+# read a manifest
+calimero-registry bundle get <package> <version> [--local]
 
-#### Create Developer
+# push a pre-built .mpk
+calimero-registry bundle push <bundle-file> [--local | --remote]
 
-```bash
-# Interactive creation
-calimero-registry developers create
-
-# Create with data
-calimero-registry developers create \
-  --name "John Doe" \
-  --email "john@example.com" \
-  --public-key "ed25519:..."
+# assemble a bundle from a bare wasm (predates cargo mero)
+calimero-registry bundle create <wasm-file> [package] [version] \
+  [-o <path>] [--name <name>] [--description <text>] [--author <author>] \
+  [--frontend <url>] [--github <url>] [--docs <url>] [--abi <path>]
 ```
 
-### Attestations
-
-#### List Attestations
+`bundle edit` is a three-step flow, because the registry only accepts a signed manifest:
 
 ```bash
-# List all attestations
-calimero-registry attestations list
-
-# List by app
-calimero-registry attestations list --app-id app-id
-
-# List by developer
-calimero-registry attestations list --developer-id developer-id
+calimero-registry bundle edit com.example.my-app 1.2.4 --remote \
+  --name "New Name" -o manifest.json     # 1. fetch with changes applied
+cargo mero sign manifest.json --key my-key.json   # 2. sign
+calimero-registry bundle edit com.example.my-app 1.2.4 --remote \
+  --manifest manifest.json               # 3. PATCH back
 ```
 
-#### Create Attestation
-
-```bash
-# Create attestation
-calimero-registry attestations create \
-  --app-id app-id \
-  --type verification \
-  --data '{"verified": true, "reason": "Security audit passed"}'
-```
+`bundle create` and `bundle push` predate `cargo mero` and know nothing about multi-service bundles, icons, or embedded ABIs. Use them only for a bundle built outside the Rust toolchain; anything built from a Calimero app crate should go through `cargo mero bundle` and `cargo mero publish`.
 
-### Local Registry Commands
+## Local registry
 
-#### Start/Stop Local Registry
+A file-backed registry for development, storing data under `~/.calimero-registry/`.
 
 ```bash
-# Start local registry
-calimero-registry local start
-
-# Start on specific port
-calimero-registry local start --port 8083
-
-# Stop local registry
-calimero-registry local stop
-
-# Check status
+calimero-registry local start [-p <port>] [-h <host>]
 calimero-registry local status
-```
-
-#### Data Management
-
-```bash
-# Seed with sample data
-calimero-registry local seed
-
-# Reset all data
-calimero-registry local reset --force
-
-# Backup data
-calimero-registry local backup
-
-# Restore from backup
-calimero-registry local restore backup.json
-```
-
-### Utility Commands
-
-#### Configuration
-
-```bash
-# List configuration
-calimero-registry config list
-
-# Set configuration value
-calimero-registry config set key value
-
-# Get configuration value
-calimero-registry config get key
-
-# Reset configuration
-calimero-registry config reset
-```
-
-#### Health Check
-
-```bash
-# Check API health
-calimero-registry health
-
-# Detailed health check
-calimero-registry health --detailed
-
-# Check local registry health
-calimero-registry health --local
-```
-
-## 🎯 Usage Examples
-
-### Complete Application Workflow
-
-```bash
-# 1. Create a new application
-calimero-registry apps create \
-  --name "DeFi Wallet" \
-  --description "A decentralized finance wallet" \
-  --version "1.0.0" \
-  --developer-id "my-developer-id"
-
-# 2. List applications to verify creation
-calimero-registry apps list --search "DeFi Wallet"
-
-# 3. Get application details
-calimero-registry apps get app-id --full
-
-# 4. Update the application
-calimero-registry apps update app-id \
-  --description "Updated DeFi wallet with new features" \
-  --version "1.1.0"
-
-# 5. Create an attestation
-calimero-registry attestations create \
-  --app-id app-id \
-  --type verification \
-  --data '{"verified": true, "audit": "passed"}'
-
-# 6. List attestations
-calimero-registry attestations list --app-id app-id
-```
-
-### Local Development Workflow
-
-```bash
-# 1. Start local registry
-calimero-registry local start
-
-# 2. Seed with sample data
-calimero-registry local seed
-
-# 3. List apps from local registry
-calimero-registry apps list --local
-
-# 4. Submit new app to local registry
-calimero-registry apps submit my-manifest.json --local
-
-# 5. Get app manifest from local registry
-calimero-registry apps manifest my-app 1.0.0 --local
-
-# 6. Check local registry health
-calimero-registry health --local
-
-# 7. Backup local data
-calimero-registry local backup
-
-# 8. Stop local registry
 calimero-registry local stop
-```
-
-### Batch Operations
-
-```bash
-# Create multiple applications from a file
-cat apps.json | calimero-registry apps create --batch
-
-# Update multiple applications
-calimero-registry apps list --output json | \
-  jq -r '.apps[].id' | \
-  xargs -I {} calimero-registry apps update {} --version "1.1.0"
-
-# Delete all applications by a developer
-calimero-registry apps list --developer-id dev-id --output json | \
-  jq -r '.apps[].id' | \
-  xargs -I {} calimero-registry apps delete {} --force
-```
-
-### Scripting Examples
-
-#### Bash Script
-
-```bash
-#!/bin/bash
-
-# Create application and get ID
-APP_ID=$(calimero-registry apps create \
-  --name "My App" \
-  --version "1.0.0" \
-  --output json | jq -r '.id')
 
-echo "Created app with ID: $APP_ID"
-
-# Wait for processing
-sleep 5
-
-# Get app details
-calimero-registry apps get "$APP_ID" --output json
-```
-
-#### Node.js Script
-
-```javascript
-const { execSync } = require('child_process');
-
-// Create application
-const createResult = JSON.parse(
-  execSync(
-    'calimero-registry apps create --name "My App" --output json'
-  ).toString()
-);
-
-const appId = createResult.id;
-console.log('Created app:', appId);
-
-// Get application details
-const appDetails = JSON.parse(
-  execSync(`calimero-registry apps get ${appId} --output json`).toString()
-);
-
-console.log('App details:', appDetails);
-```
-
-## 🔧 Advanced Features
-
-### Output Formats
-
-#### JSON Output
-
-```bash
-calimero-registry apps list --output json
+calimero-registry local seed                    # sample data
+calimero-registry local reset [-f]
+calimero-registry local backup [-o <file>]
+calimero-registry local restore <backup-file>
 ```
 
-```json
-{
-  "apps": [
-    {
-      "id": "app-1",
-      "name": "My App",
-      "version": "1.0.0",
-      "developer": {
-        "id": "dev-1",
-        "name": "John Doe"
-      }
-    }
-  ],
-  "total": 1,
-  "limit": 20,
-  "offset": 0
-}
-```
+Commands that accept `--local` (`bundle get`, `bundle push`) then work against it instead of the remote registry.
 
-#### Table Output
+## Other
 
 ```bash
-calimero-registry apps list --output table
+calimero-registry health                        # check the API is reachable
+calimero-registry ipfs upload   <file>
+calimero-registry ipfs download <cid> [output]
 ```
 
-```
-┌─────────┬──────────┬─────────┬─────────────┐
-│ ID      │ Name     │ Version │ Developer   │
-├─────────┼──────────┼─────────┼─────────────┤
-│ app-1   │ My App   │ 1.0.0   │ John Doe    │
-└─────────┴──────────┴─────────┴─────────────┘
-```
-
-#### YAML Output
+## Development
 
 ```bash
-calimero-registry apps list --output yaml
+pnpm build        # tsup
+pnpm test         # vitest
+pnpm lint         # eslint, zero warnings
+pnpm type-check   # tsc --noEmit
 ```
 
-```yaml
-apps:
-  - id: app-1
-    name: My App
-    version: 1.0.0
-    developer:
-      id: dev-1
-      name: John Doe
-total: 1
-limit: 20
-offset: 0
-```
-
-### Interactive Mode
-
-```bash
-# Start interactive mode
-calimero-registry interactive
-
-# Available commands in interactive mode:
-# > apps list
-# > apps create
-# > developers list
-# > help
-# > exit
-```
-
-### Auto-completion
-
-```bash
-# Enable auto-completion for bash
-calimero-registry completion bash > ~/.bash_completion
-
-# Enable auto-completion for zsh
-calimero-registry completion zsh > ~/.zsh_completion
-
-# Enable auto-completion for fish
-calimero-registry completion fish > ~/.config/fish/completions/calimero-registry.fish
-```
-
-## 🧪 Testing
-
-### Running Tests
-
-```bash
-# Run all tests
-pnpm test
-
-# Run tests in watch mode
-pnpm test:watch
-
-# Run tests with coverage
-pnpm test:coverage
-
-# Run specific test file
-pnpm test src/commands/apps.test.ts
-```
-
-### Test Examples
-
-#### Command Test
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import { AppsCommand } from '../src/commands/apps';
-
-describe('AppsCommand', () => {
-  it('should list applications', async () => {
-    const command = new AppsCommand();
-    const result = await command.list({ limit: 10 });
-
-    expect(result.apps).toBeDefined();
-    expect(Array.isArray(result.apps)).toBe(true);
-  });
-});
-```
-
-#### Integration Test
-
-```typescript
-describe('CLI Integration', () => {
-  it('should create and delete application', async () => {
-    // Create app
-    const createResult = await cli.run([
-      'apps',
-      'create',
-      '--name',
-      'Test App',
-      '--version',
-      '1.0.0',
-      '--output',
-      'json',
-    ]);
-
-    const appId = JSON.parse(createResult).id;
-    expect(appId).toBeDefined();
-
-    // Delete app
-    await cli.run(['apps', 'delete', appId, '--force']);
-  });
-});
-```
-
-## 🚀 Build & Distribution
-
-### Building the CLI
-
-```bash
-# Build the CLI
-pnpm build
-
-# Build with shebang for direct execution
-pnpm build:cli
-
-# Build for different platforms
-pnpm build:linux
-pnpm build:macos
-pnpm build:windows
-```
-
-### Publishing
-
-```bash
-# Publish to npm
-pnpm publish
-
-# Publish with specific tag
-pnpm publish --tag beta
-```
-
-## 🔧 Development
-
-### Development Commands
-
-```bash
-# Install dependencies
-pnpm install
-
-# Build the CLI
-pnpm build
-
-# Run tests
-pnpm test
-
-# Run tests in watch mode
-pnpm test:watch
-
-# Lint code
-pnpm lint
-
-# Fix linting issues
-pnpm lint:fix
-
-# Format code
-pnpm format
-
-# Type checking
-pnpm type-check
-```
-
-### Code Quality
-
-- **ESLint**: Code linting with TypeScript rules
-- **Prettier**: Code formatting
-- **TypeScript**: Static type checking
-- **Vitest**: Unit testing framework
-- **Coverage**: Test coverage reporting
-
-## 📄 License
-
-This package is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.
-
-## 🤝 Contributing
-
-See the main [CONTRIBUTING](../../CONTRIBUTING.md) guide for details on how to contribute to this package.
-
-## 🆘 Support
+## License
 
-- **Issues**: Create an issue on GitHub
-- **Documentation**: Check the command help with `--help`
-- **Examples**: Review the test suite for usage examples
+MIT. See [LICENSE.md](../../LICENSE.md).