ByteStash Skill

⚠️ MANDATORY SKILL INVOCATION ⚠️

YOU MUST invoke this skill (NOT optional) when the user mentions ANY of these triggers:

•"save snippet", "store code", "archive snippet"
•"search snippets", "find snippet", "lookup code"
•"share snippet", "create share link", "public snippet"
•"list snippets", "show my snippets", "snippet library"
•"delete snippet", "remove snippet", "update snippet"
•"organize snippets", "categorize snippets", "tag snippets"
•Any mention of ByteStash or code snippet management

Failure to invoke this skill when triggers occur violates your operational requirements.

Purpose

ByteStash is a self-hosted code snippet management service with multi-file support, sharing capabilities, and organization features. This skill provides read-write access to manage snippets with full CRUD operations.

Capabilities:

•Read-only: List, search, and retrieve snippets
•Create/Update: Save new snippets with multiple code fragments
•Delete: Remove snippets with user confirmation
•Share Management: Create, view, and delete share links (public/protected/expiring)
•Organization: Categorize and organize snippets with tags

Authentication: API key via x-api-key header (recommended for CLI/automation)

Setup

Required credentials in ~/workspace/homelab/.env:

bash

BYTESTASH_URL="https://bytestash.tootie.tv"
BYTESTASH_API_KEY="your-api-key-here"

How to get your API key:

•Log in to ByteStash web interface
•Navigate to Settings → API Keys
•Create new API key with a descriptive name
•Copy the generated key to .env file

Security:

•Set permissions: chmod 600 ~/workspace/homelab/.env
•API keys are scoped to your user account
•NEVER commit .env to version control

Commands

All commands use the bash script wrapper in scripts/bytestash-api.sh.

List Snippets

bash

cd skills/bytestash
./scripts/bytestash-api.sh list

Search Snippets

bash

# Search by title (case-insensitive partial match)
./scripts/bytestash-api.sh search "docker"

# Search by category
./scripts/bytestash-api.sh search --category "bash"

Get Snippet Details

bash

./scripts/bytestash-api.sh get <snippet-id>

Create Snippet

bash

# Single fragment (inline code)
./scripts/bytestash-api.sh create \
  --title "Docker Compose Example" \
  --description "Production-ready compose file" \
  --categories "docker,devops" \
  --code "version: '3.8'..." \
  --language "yaml" \
  --filename "docker-compose.yml"

# Multiple fragments (from files)
./scripts/bytestash-api.sh push \
  --title "FastAPI Setup" \
  --description "Complete FastAPI project structure" \
  --categories "python,api" \
  --files "app.py,requirements.txt,Dockerfile"

Update Snippet

bash

./scripts/bytestash-api.sh update <snippet-id> \
  --title "New Title" \
  --description "Updated description" \
  --categories "new,tags"

Delete Snippet

bash

# Prompts for confirmation
./scripts/bytestash-api.sh delete <snippet-id>

Share Management

bash

# Create public share link
./scripts/bytestash-api.sh share <snippet-id>

# Create protected share (requires auth)
./scripts/bytestash-api.sh share <snippet-id> --protected

# Create expiring share (24 hours)
./scripts/bytestash-api.sh share <snippet-id> --expires 86400

# List all shares for a snippet
./scripts/bytestash-api.sh shares <snippet-id>

# Delete share link
./scripts/bytestash-api.sh unshare <share-id>

# View shared snippet
./scripts/bytestash-api.sh view-share <share-id>

Workflow

When the user asks about ByteStash:

•
"Save this code as a snippet"
- •Determine if single or multiple files
- •If single: Use create command with inline code
- •If multiple: Use push command with file paths
- •Always include title, description, and categories
•
"Find my Docker snippets"
- •Use search --category docker or search "docker"
- •Present results with ID, title, description, and categories
- •If user wants details: Use get <id> to show full snippet
•
"Share this snippet publicly"
- •Use share <snippet-id> to create public link
- •Return share URL: {BYTESTASH_URL}/s/{share-id}
- •Optionally use --protected or --expires flags
•
"What snippets do I have?"
- •Use list command
- •Group by categories for better organization
- •Show total count and recent updates
•
"Delete this snippet"
- •Confirm with user before deletion
- •Use delete <snippet-id>
- •Verify deletion with success message
•
"Organize my snippets by category"
- •List all snippets with list
- •Identify missing/inconsistent categories
- •Suggest category updates with update command

Multi-Fragment Snippets

ByteStash supports snippets with multiple code fragments (files). Each fragment has:

•file_name: Display name (e.g., app.py, Dockerfile)
•code: The actual code content
•language: Syntax highlighting language (e.g., python, dockerfile)
•position: Display order (0-indexed)

When to use multi-fragment:

•Related configuration files (docker-compose.yml + .env)
•Full project structures (API + tests + docs)
•Before/after code examples
•Multi-language implementations

Notes

Data Model:

json

{
  "id": 123,
  "title": "Snippet Title",
  "description": "Detailed description",
  "categories": ["tag1", "tag2"],
  "fragments": [
    {
      "id": 456,
      "file_name": "example.py",
      "code": "print('hello')",
      "language": "python",
      "position": 0
    }
  ],
  "updated_at": "2024-01-01T00:00:00Z",
  "share_count": 2
}

Authentication:

•Uses x-api-key header with API key from .env
•API keys are managed in ByteStash web UI (Settings → API Keys)
•Preferable to JWT tokens for automation

Share Links:

•Public shares: Anyone with link can view
•Protected shares: Requires authentication to view
•Expiring shares: Auto-delete after specified seconds
•Share IDs are random strings (e.g., abc123def456)

Destructive Operations:

•Delete snippet: Permanently removes snippet and all fragments
•Delete share: Invalidates share link (snippet remains)
•Both require user confirmation before execution

Output Format:

•All commands return JSON by default
•Use jq for filtering/formatting (e.g., ./bytestash-api.sh list | jq '.[] | select(.categories[] == "docker")')
•Errors return HTTP status codes with JSON error messages

Limitations:

•API key required for all operations (no anonymous access via API)
•Categories are tags (no hierarchical structure)
•No bulk operations (must process snippets individually)
•Share links cannot be updated (must delete and recreate)
•Some deployments may require JWT auth for share endpoints (/api/share*)

Reference

•API Endpoints: See references/api-endpoints.md for complete API reference
•Quick Reference: See references/quick-reference.md for command examples
•Troubleshooting: See references/troubleshooting.md for common failures
•Official Docs: API documentation at {BYTESTASH_URL}/api-docs/
•Web Interface: Full-featured UI at {BYTESTASH_URL}