# Bytestash

> Manage code snippets in ByteStash snippet storage service. This skill should be used when the user asks to "save a snippet", "search snippets", "find code", "share snippet", "organize snippets", "list my snippets", "create snippet", "delete snippet", or mentions ByteStash, code storage, snippet management, or code archival. Use when this capability is needed.

- Skill: `tomevault-io/bytestash` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/bytestash`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/bytestash/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/bytestash

---


# 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 `~/.claude-homelab/.env`:**

```bash
BYTESTASH_URL="https://bytestash.example.com"
BYTESTASH_API_KEY="<your_api_key>"
```

**How to get your API key:**
1. Log in to ByteStash web interface
2. Navigate to Settings → API Keys
3. Create new API key with a descriptive name
4. Copy the generated key to `.env` file

**Security:**
- Set permissions: `chmod 600 ~/.claude-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:

1. **"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

2. **"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

3. **"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

4. **"What snippets do I have?"**
   - Use `list` command
   - Group by categories for better organization
   - Show total count and recent updates

5. **"Delete this snippet"**
   - Confirm with user before deletion
   - Use `delete <snippet-id>`
   - Verify deletion with success message

6. **"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}`

---

## 🔧 Agent Tool Usage Requirements

**CRITICAL:** When invoking scripts from this skill via the zsh-tool, **ALWAYS use `pty: true`**.

Without PTY mode, command output will not be visible even though commands execute successfully.

**Correct invocation pattern:**
```typescript
<invoke name="mcp__plugin_zsh-tool_zsh-tool__zsh">
<parameter name="command">./skills/bytestash/scripts/bytestash-api.sh [args]</parameter>
<parameter name="pty">true</parameter>
</invoke>
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/jmagar) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->