---
name: zopub
description: Publish directories as public file collections on zo.pub using the zopub CLI. Sync local folders to create browsable, shareable collections with direct download links. Use when the user wants to share files publicly, publish datasets, or manage zo.pub collections.
compatibility: Created for Zo Computer
metadata:
  author: rob.zo.computer
---
## Overview

`zopub` syncs local directories to **zo.pub**, a public file hosting service integrated with Zo Computer. Each synced directory becomes a "collection" — a browsable page with direct download links for every file.

Collections are publicly accessible at `https://zo.pub/rob/<collection-name>`.
Individual files are at `https://zo.pub/rob/<collection-name>/<filename>`.

## When to Use

- User wants to share a folder of files publicly
- User wants to publish a dataset, document collection, or media gallery
- User says "publish to zo.pub", "make this public", "share these files"
- User asks to list, update, or remove zo.pub collections

## CLI Reference

```bash
# List all collections
zopub ls

# Sync a directory to a collection (creates or updates)
zopub sync <name> <source-dir>

# Remove a collection
zopub rm <name>
```

### Collection Names

- Lowercase alphanumeric with hyphens only (e.g. `my-dataset`, `photos2024`)
- No leading/trailing hyphens, no consecutive hyphens
- Regex: `^[a-z0-9][a-z0-9-]*[a-z0-9]$` or single char `^[a-z0-9]$`

### Sync Behavior

`zopub sync` is incremental — it compares SHA-256 hashes and only copies changed files. Output shows counts of added/changed/deleted/unchanged files. On first sync it creates the collection; subsequent syncs update it.

The sync writes files to `/mnt/pub/<name>/` along with a `.zopub.json` manifest containing metadata (title, timestamps, file entries with sizes and content types).

### Titles

By default the title is derived from the collection name (hyphen-to-space, title-cased). Existing titles are preserved across syncs.

## Workflow

1. **Identify the source directory** the user wants to publish.
2. **Choose a collection name** — derive from the directory name or ask the user.
3. **Run the sync:**
   ```bash
   zopub sync <name> /path/to/source-dir
   ```
4. **Report the public URL:** `https://zo.pub/rob/<name>`

To update, just re-run `zopub sync` with the same name — only changes are transferred.

## Examples

```bash
# Publish a research dataset
zopub sync climate-data /home/workspace/datasets/climate/source

# Publish exported documents
zopub sync tax-docs-2025 /home/workspace/Documents/tax-2025

# Check what's published
zopub ls

# Remove a collection
zopub rm old-collection
```