anyt-cli 0.1.0

package/CLI_GUIDE.md

@@ -0,0 +1,772 @@
+# anyt CLI Guide
+
+anyt is a package manager for AI agent skills. It provides commands for authentication, configuration, skill management, and publishing across AI agents.
+
+## Installation
+
+```bash
+# Install globally
+npm install -g anyt-skill-cli
+
+# Or use with npx
+npx anyt-skill-cli <command>
+```
+
+## Command Reference
+
+```
+Usage: anyt-skill [options] [command]
+
+Package manager for AI agent skills
+
+Options:
+  -V, --version                              output the version number
+  -h, --help                                 display help for command
+
+Commands:
+  config                                     Manage anyt configuration (show, init, set-encryption-key, get-encryption-key, remove-encryption-key)
+  login [options]                            Log in via browser or with an API key
+  logout                                     Log out and clear stored credentials
+  whoami                                     Show current user information
+  init [options]                             Create a new anyt.json manifest in the current directory
+  migrate [options]                          Migrate from old directory structure (.skills/, skill-lock.json)
+  add [options] <specifiers...>              Add one or more skills
+  remove|rm <name>                           Remove an installed skill
+  list|ls [options]                          List installed skills
+  install|i [options] [specifiers...]        Install skills from lockfile, or add and install specific packages
+  link [options]                             Recreate agent symlinks without reinstalling
+  update [options]                           Update all skills to latest compatible versions
+  search|find [options] [query]              Search and discover skills from the registry
+  audit [options]                            Verify integrity of installed skills
+  outdated [options] [packages...]           Check for outdated skills
+  version <bump>                             Bump package version (major, minor, patch)
+  publish [options]                          Publish current directory as a skill
+  unpublish [options] <specifier>            Remove a published skill version (only within 72 hours of publishing)
+  access [options] [specifier]               Change package visibility (public/private)
+  deprecate [options] <specifier> [message]  Mark a skill version as deprecated (alternative to unpublish after 72 hours)
+  skill-list                                 Manage skill lists (list, create, show, update, delete, add-skill, remove-skill, install)
+  notebook                                   Manage notebooks (upload, list, download, delete)
+  upgrade                                    Update anyt-skill itself to the latest version
+  help [command]                             display help for command
+```
+
+## Authentication
+
+### Login
+
+Authenticate with an API key:
+
+```bash
+anyt-skill login --api-key <key>
+```
+
+Or use browser-based OAuth:
+
+```bash
+anyt-skill login
+```
+
+### Logout
+
+Remove stored credentials:
+
+```bash
+anyt-skill logout
+```
+
+### Who Am I
+
+Display current user information:
+
+```bash
+anyt-skill whoami
+
+# Output:
+#   Username: myuser
+#   User ID: user_123
+#   Registry: https://registry.anyt.io
+```
+
+## Configuration
+
+### Show Configuration
+
+Display resolved configuration and config file locations:
+
+```bash
+anyt-skill config show
+
+# Output:
+#   Resolved Configuration:
+#
+#     Registry URL:   https://registry.anyt.io
+#     API Key:        ***
+#     Username:       myuser
+#
+#   Config Locations:
+#     User config:    /Users/you/.anytrc
+#     Project config: (none)
+#
+#   Environment Variables:
+#     ANYT_REGISTRY_URL: (not set)
+#     ANYT_API_KEY:      (not set)
+```
+
+### Initialize Project Config
+
+Create a `.anytrc` file in the current directory:
+
+```bash
+anyt-skill config init
+anyt-skill config init --registry https://custom.example.com
+```
+
+## Project Initialization
+
+### Initialize Manifest
+
+Create a new `anyt.json` manifest file in the current directory:
+
+```bash
+anyt-skill init                          # Interactive prompts
+anyt-skill init -y                       # Use defaults, skip prompts
+anyt-skill init -n my-skill              # Specify name
+anyt-skill init -d "My skill"            # Specify description
+anyt-skill init -a "Your Name"           # Specify author
+anyt-skill init -f                       # Overwrite existing anyt.json
+```
+
+### Migrate from Old Structure
+
+Migrate from old directory structure (`.skills/`, `skill-lock.json`):
+
+```bash
+anyt-skill migrate                       # Perform migration
+anyt-skill migrate --dry-run             # Preview changes without applying
+```
+
+## Skill Management
+
+### Add Skill
+
+Add a skill to the project and install it:
+
+```bash
+anyt-skill add <specifier> [--agent <agents>]
+
+# Registry specifier formats:
+anyt-skill add @user/bsheng/vite_slides           # Latest version
+anyt-skill add @user/bsheng/vite_slides@2.0.0     # Specific version
+anyt-skill add @user/bsheng/vite_slides@^2.0.0    # Semver range
+
+# GitHub specifier formats:
+anyt-skill add github:owner/repo                  # Entire repo, default branch
+anyt-skill add github:owner/repo@main             # Entire repo, specific branch
+anyt-skill add github:owner/repo/path/to/skill    # Subdirectory, default branch
+anyt-skill add github:owner/repo/path@v1.0.0      # Subdirectory with tag/ref
+
+# Local directory specifiers (for development):
+anyt-skill add file:../my-skill                   # Relative path
+anyt-skill add file:./local-skill                 # Current directory relative
+anyt-skill add file:/absolute/path/to/skill       # Absolute path
+
+# Add multiple skills at once:
+anyt-skill add @user/alice/skill1 @user/bob/skill2
+
+# Agent options:
+anyt-skill add @user/skill --agent claude-code,cursor  # Link to multiple agents
+anyt-skill add github:owner/repo --agent none          # Skip symlink creation
+anyt-skill add @user/skill -y                          # Skip agent selection prompt
+anyt-skill add @user/skill -g                          # Install to user home directory
+```
+
+### Remove Skill
+
+```bash
+anyt-skill remove <name>
+anyt-skill rm <name>
+
+# Examples:
+anyt-skill remove vite_slides
+anyt-skill rm @user/bsheng/vite_slides
+```
+
+### List Skills
+
+```bash
+anyt-skill list
+anyt-skill ls
+
+# JSON output for scripting
+anyt-skill list --json
+
+# List global skills
+anyt-skill list -g
+
+# Example output:
+# Installed skills:
+#
+#   @user/alice/code-review@1.2.0 (registry)
+#     -> .claude/skills/code-review
+#
+#   github:owner/repo/skills/react-tips (main@abc1234)
+#     -> .claude/skills/react-tips, .cursor/skills/react-tips
+#
+# Total: 2 skill(s) (1 registry, 1 github)
+```
+
+### Install Skills
+
+Install all skills from the lockfile:
+
+```bash
+anyt-skill install
+anyt-skill i
+
+# With options:
+anyt-skill install --frozen-lockfile           # CI/CD mode - fail if lockfile missing
+anyt-skill install --dir ./vendor/skills       # Install to specific directory
+anyt-skill install --agent claude-code,cursor  # Link to multiple agents
+anyt-skill install --agent none                # Skip symlink creation
+anyt-skill install -y                          # Skip agent selection prompt
+anyt-skill install -g                          # Install to user home directory
+
+# Install specific packages (like npm):
+anyt-skill install @user/alice/skill1 github:org/repo
+
+# Install all skills from a skill list:
+anyt-skill install --list @user/alice/my-favorites
+anyt-skill install --list @org/myteam/starter-kit
+```
+
+### Link Skills
+
+Recreate agent symlinks without reinstalling (useful after adding agents):
+
+```bash
+anyt-skill link
+anyt-skill link --agent claude-code,cursor  # Link to specific agents
+anyt-skill link -y                          # Skip agent selection prompt
+anyt-skill link -g                          # Recreate global agent symlinks
+```
+
+### Update Skills
+
+```bash
+anyt-skill update
+anyt-skill update --dry-run    # Preview updates without applying
+```
+
+### Search Skills
+
+Search and discover skills from the registry:
+
+```bash
+anyt-skill search typescript        # Search by keyword
+anyt-skill find react               # Alias for search
+anyt-skill search react --json      # JSON output
+anyt-skill search --sort recent --limit 10
+```
+
+### Check Outdated Skills
+
+```bash
+anyt-skill outdated                 # Check all packages
+anyt-skill outdated code-review     # Check specific package
+anyt-skill outdated --json          # JSON output
+anyt-skill outdated --all           # Include up-to-date packages
+```
+
+Exits with code `1` if any packages are outdated.
+
+### Audit Skills
+
+Verify integrity of installed skills:
+
+```bash
+anyt-skill audit                    # Human-readable output
+anyt-skill audit --json             # JSON output (for CI)
+```
+
+Checks for: missing packages, deprecated versions, corrupted installations.
+
+## Versioning
+
+### Bump Version
+
+Bump the package version in `anyt.json` without publishing (similar to `npm version`):
+
+```bash
+anyt-skill version <bump>
+
+# Bump types:
+anyt-skill version major      # 1.0.0 → 2.0.0
+anyt-skill version minor      # 1.0.0 → 1.1.0
+anyt-skill version patch      # 1.0.0 → 1.0.1
+
+# Options:
+anyt-skill version patch --dry-run   # Preview what would change
+```
+
+The command:
+- Reads the current version from `anyt.json`
+- Increments the version according to semver rules
+- Writes the updated version back to `anyt.json`
+- Outputs the new version (e.g., `v1.0.1`)
+
+## Publishing
+
+### Publish Skill
+
+Publish the current directory as a skill:
+
+```bash
+anyt-skill publish --access public          # Publish as public
+anyt-skill publish --access private         # Publish as private
+anyt-skill publish --access team --org myorg # Publish under org
+anyt-skill publish --access public --bump patch    # Auto-bump version
+anyt-skill publish --access public --bump minor --tag beta
+```
+
+The `--access` flag is required and must be `public`, `private`, or `team`.
+
+**Required `anyt.json` fields:**
+- `name` - Skill name (e.g., `@user/username/skillname`)
+- `version` - Semver version
+
+**Optional `anyt.json` fields:**
+- `description` - Skill description
+- `author` - Author name
+- `files` - Files to include (default: `["anyt.json", "SKILL.md", "runtime", "scripts", "data"]`)
+
+### Unpublish Skill
+
+Remove a published skill version (only within 72 hours of publishing):
+
+```bash
+anyt-skill unpublish <specifier> --force
+
+# Delete specific version (user skills only)
+anyt-skill unpublish @user/bsheng/vite_slides@2.0.0 --force
+
+# Delete all versions (user skill)
+anyt-skill unpublish @user/bsheng/vite_slides --force
+
+# Delete all versions (org skill)
+anyt-skill unpublish @org/myorg/team-skill --force
+```
+
+**Note:** Version-specific deletion for org skills is not yet supported. Use the full skill specifier without a version to delete the entire org skill.
+
+### Deprecate Skill
+
+Mark a skill version as deprecated (alternative to unpublish after 72 hours):
+
+```bash
+anyt-skill deprecate <specifier> [message]
+
+# Deprecate with message
+anyt-skill deprecate @user/bsheng/old-skill@1.0.0 "Use @user/bsheng/new-skill instead"
+
+# Remove deprecation
+anyt-skill deprecate @user/bsheng/old-skill@1.0.0 --undo
+```
+
+## Visibility
+
+### Change Package Visibility
+
+Change a package's visibility between public and private:
+
+```bash
+# Make current package public
+anyt-skill access --public
+
+# Make specific package public
+anyt-skill access @user/bsheng/vite_slides --public
+```
+
+**Important:** Making a package public is irreversible (following npm conventions). Public packages cannot be made private again.
+
+- **Private packages** (default): Require authentication to download
+- **Public packages**: Anyone can download without authentication
+
+## Client-Side Encryption
+
+Private packages can be encrypted before upload so that the anyt server and storage (R2) only ever see ciphertext. The encryption key never leaves your machine.
+
+### How It Works
+
+- **Publish:** If an encryption key is set for the package scope, the CLI encrypts the tarball with AES-256-GCM before uploading. The server stores only ciphertext.
+- **Install:** The CLI checks the package manifest for encryption metadata. If present, it decrypts the tarball locally before extracting.
+- **Public packages** are never encrypted — encryption only applies to `private` and `team` visibility.
+
+### Set an Encryption Key
+
+Each scope (`@user/yourname` or `@org/orgname`) has one encryption key. All private packages under that scope use the same key.
+
+```bash
+# Set encryption key for your user scope
+anyt-skill config set-encryption-key @user/yourname my-secret-passphrase
+
+# Set encryption key for an organization
+anyt-skill config set-encryption-key @org/myorg shared-team-secret
+```
+
+Or use environment variables:
+
+```bash
+export ANYT_ENCRYPTION_KEY_USER_YOURNAME="my-secret-passphrase"
+export ANYT_ENCRYPTION_KEY_ORG_MYORG="shared-team-secret"
+```
+
+### Manage Encryption Keys
+
+```bash
+# Check if a key is set
+anyt-skill config get-encryption-key @user/yourname
+
+# Remove a key
+anyt-skill config remove-encryption-key @user/yourname
+```
+
+### Publish with Encryption
+
+When you publish a private package and an encryption key is configured for the scope, the CLI automatically encrypts:
+
+```bash
+anyt-skill config set-encryption-key @user/yourname my-secret
+anyt-skill publish --access private
+# Output: anyt-skill notice Encrypting package (scope: @user/yourname)
+```
+
+If no encryption key is set, the package is uploaded unencrypted with a warning.
+
+### Install Encrypted Packages
+
+```bash
+# Set the same key used during publish
+anyt-skill config set-encryption-key @user/yourname my-secret
+
+# Install as usual — decryption is automatic
+anyt-skill install
+```
+
+If you don't have the key, the CLI will show an error with instructions:
+
+```
+Error: Package @user/yourname/my-skill is encrypted.
+Set the key: anyt-skill config set-encryption-key @user/yourname <passphrase>
+```
+
+### Team Sharing
+
+For organization packages, share the encryption key with team members through a secure channel (e.g., a password manager). Each team member adds it to their local config:
+
+```bash
+anyt-skill config set-encryption-key @org/myorg shared-team-secret
+```
+
+### Important Notes
+
+- **Key loss = data loss.** If you lose your encryption key, encrypted packages cannot be recovered. Back up your keys.
+- The server stores encryption metadata (algorithm, salt, IV) alongside the package — these are not secrets and are safe to store publicly.
+- Encryption is opt-in. If no key is configured, private packages are uploaded unencrypted.
+
+## Configuration Files
+
+### User Config: `~/.anytrc`
+
+INI format configuration file:
+
+```ini
+; anyt Configuration
+
+registry = https://registry.anyt.io
+authToken = sk_...
+username = myuser
+
+; Multi-registry: Scope mappings (optional)
+@myorg:registry = https://corp.anyt.io
+
+; Multi-registry: Per-registry tokens (optional)
+//anyt.io:authToken = sk_public_token
+//corp.anyt.io:authToken = sk_corp_token
+
+; Encryption keys (optional)
+encryption-key:@user/yourname = my-secret-passphrase
+encryption-key:@org/myorg = shared-team-secret
+```
+
+### Project Config: `.anytrc`
+
+Project-specific configuration (optional):
+
+```ini
+; Project-specific anyt configuration
+
+registry = https://custom.example.com
+```
+
+### Manifest: `anyt.json`
+
+Package manifest file (created with `anyt-skill init`):
+
+```json
+{
+  "name": "@user/username/my-skill",
+  "version": "1.0.0",
+  "description": "A helpful skill for...",
+  "author": "Your Name",
+  "files": ["anyt.json", "SKILL.md", "runtime", "scripts", "data"],
+  "dependencies": {
+    "@user/other/skill": "^1.0.0"
+  },
+  "githubDependencies": {
+    "github:owner/repo/skills/example": "main"
+  },
+  "localDependencies": {
+    "file:../my-local-skill": "*"
+  }
+}
+```
+
+### Lockfile: `anyt-lock.json`
+
+```json
+{
+  "lockfileVersion": 4,
+  "registryUrl": "https://registry.anyt.io",
+  "packages": {
+    "@user/bsheng/vite_slides": {
+      "version": "2.0.0",
+      "resolved": "https://registry.anyt.io/...",
+      "integrity": "sha256-abc123..."
+    }
+  },
+  "githubPackages": {
+    "github:owner/repo/path": {
+      "version": "abc1234",
+      "resolved": "https://github.com/owner/repo",
+      "integrity": "sha256-...",
+      "gitCommit": "abc1234567890...",
+      "gitRef": "main"
+    }
+  },
+  "localPackages": {
+    "file:../my-local-skill": {
+      "version": "local",
+      "path": "../my-local-skill",
+      "resolvedPath": "/absolute/path/to/my-local-skill",
+      "name": "my-local-skill"
+    }
+  }
+}
+```
+
+## Configuration Resolution
+
+Configuration is resolved in priority order:
+
+1. **Environment Variables** (`ANYT_REGISTRY_URL`, `ANYT_API_KEY`) - Highest
+2. **Project Config** (`.anytrc` in project directory)
+3. **User Config** (`~/.anytrc`)
+4. **Defaults** - Lowest
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `ANYT_API_KEY` | Override API key |
+| `ANYT_DEBUG` | Enable debug logging |
+| `GITHUB_TOKEN` | GitHub token for private repos and higher rate limits |
+| `ANYT_ENCRYPTION_KEY_<SCOPE>` | Encryption key for a scope (e.g., `ANYT_ENCRYPTION_KEY_USER_ALICE`) |
+
+## Directory Structure
+
+```
+project/
+├── .anytrc              # Project config (optional)
+├── anyt.json            # Manifest with dependencies
+├── anyt-lock.json       # Lockfile
+├── .anyt/
+│   ├── skills/          # Installed skills
+│   │   ├── {username}/  # Registry skills
+│   │   │   └── {skillname}/
+│   │   ├── _github/     # GitHub skills
+│   │   │   └── {owner}/
+│   │   │       └── {repo}/
+│   │   │           └── {path}/
+│   │   └── _local/      # Local skill symlinks
+│   │       └── {name} -> ../../../path/to/local/skill
+│   └── cache/           # Tarball cache
+├── .claude/
+│   └── skills/          # Symlinks for claude-code agent
+└── .cursor/
+    └── skills/          # Symlinks for cursor agent (if configured)
+
+~/
+└── .anytrc              # User config
+```
+
+## Common Workflows
+
+### CI/CD Integration
+
+```bash
+# Use environment variable for authentication
+export ANYT_API_KEY=sk_ci_key
+
+# Install with frozen lockfile (fails if lockfile missing or outdated)
+anyt-skill install --frozen-lockfile
+```
+
+### Local Development Workflow
+
+Use local dependencies to develop and test skills before publishing:
+
+```bash
+# Add a local skill for development
+anyt-skill add file:../my-skill
+
+# The skill is symlinked, so changes are instant
+# No need to reinstall after editing the local skill
+
+# When ready to publish
+cd ../my-skill
+anyt-skill publish
+```
+
+In your `anyt.json`:
+```json
+{
+  "localDependencies": {
+    "file:../my-local-skill": "*"
+  }
+}
+```
+
+### Publishing Workflow
+
+```bash
+# Initialize a new skill
+anyt-skill init
+
+# Edit anyt.json and create SKILL.md
+# Then publish with auto-bump
+anyt-skill publish --bump patch
+```
+
+## Skill Lists
+
+### List Skill Lists
+
+```bash
+anyt-skill skill-list list              # Your lists
+anyt-skill skill-list list --org myorg  # Organization's lists
+anyt-skill skill-list list --json       # JSON output
+```
+
+### Create Skill List
+
+```bash
+anyt-skill skill-list create my-favorites
+anyt-skill skill-list create my-favorites --visibility public
+anyt-skill skill-list create team-tools --org myorg -d "Our team's tools"
+```
+
+### Show Skill List
+
+```bash
+anyt-skill skill-list show @user/alice/my-favorites
+anyt-skill skill-list show @org/myorg/team-tools --json
+```
+
+### Update Skill List
+
+```bash
+anyt-skill skill-list update @user/alice/my-favorites --description "Updated desc"
+anyt-skill skill-list update @user/alice/my-favorites --visibility public
+```
+
+### Delete Skill List
+
+```bash
+anyt-skill skill-list delete @user/alice/my-favorites
+```
+
+### Add Skill to List
+
+```bash
+anyt-skill skill-list add-skill @user/alice/my-favorites @user/bob/code-review
+anyt-skill skill-list add-skill @user/alice/my-favorites @user/bob/lint --note "Great for CI"
+```
+
+### Remove Skill from List
+
+```bash
+anyt-skill skill-list remove-skill @user/alice/my-favorites @user/bob/code-review
+```
+
+### Install from Skill List
+
+```bash
+anyt-skill skill-list install @user/alice/my-favorites
+anyt-skill skill-list install @org/myorg/team-tools --agent claude-code
+```
+
+## Notebook Management
+
+### Upload Notebook
+
+```bash
+anyt-skill notebook upload notebook.anyt.md
+anyt-skill notebook upload notebook.anyt.md --visibility public
+anyt-skill notebook upload notebook.anyt.md --org myorg
+```
+
+### List Notebooks
+
+```bash
+anyt-skill notebook list
+anyt-skill notebook list --org myorg
+anyt-skill notebook list --json
+```
+
+### Download Notebook
+
+```bash
+anyt-skill notebook download <id>
+```
+
+### Delete Notebook
+
+```bash
+anyt-skill notebook delete <id>
+```
+
+## Self-Update
+
+### Upgrade anyt-cli
+
+Update anyt-skill itself to the latest version:
+
+```bash
+anyt-skill upgrade
+```
+
+Auto-detects your package manager (pnpm, npm, yarn, bun). The CLI also checks for updates every 24 hours and notifies you when a newer version is available.
+
+## Troubleshooting
+
+| Error | Solution |
+|-------|----------|
+| "Not logged in" | Run `anyt-skill login --api-key <key>` |
+| "Invalid skill specifier" | Use format: `@user/{username}/{name}[@version]` |
+| "No lockfile found" | Run `anyt-skill add <specifier>` first |
+
+Enable debug mode for detailed output:
+
+```bash
+ANYT_DEBUG=1 anyt <command>
+```