RefPack CLI Usage Guide

This guide provides detailed examples for using the RefPack CLI to create, validate, push, pull, and inspect dataset packages according to the RefPack specification.

1. Scaffold a New RefPack

Create a new RefPack folder with all required files, a signing key, and a key ID:

refpack scaffold --output ./my-refpack --id myid --title "My Dataset" --author "Your Name"

This creates the folder my-refpack/ with:
- data.meta.json, data.json, data.schema.json, data.changelog.json, data.readme.md, and assets/
- sign-key.pem (private key for signing)
- key-id.txt (key identifier)

2. Pack & Sign a RefPack

Package and sign the dataset folder into a distributable ZIP file:

refpack pack \
  --input ./my-refpack/ \
  --output myid-1.0.0.refpack.zip \
  --sign-key ./my-refpack/sign-key.pem \
  --key-id $(cat ./my-refpack/key-id.txt)

Validates the folder structure and manifest.
Signs data.meta.json and creates data.meta.json.jws.
Produces myid-1.0.0.refpack.zip.

3. Validate a RefPack ZIP

Verify the structure, schemas, and JWS signature of a package:

refpack validate \
  --package myid-1.0.0.refpack.zip \
  --verbose


            
                Checks ZIP layout, manifest schema, and signature.



        
            4. Push to a Registry
            Upload a package to a remote registry (like this RefPack Gallery):
            
                refpack push \
  --package myid-1.0.0.refpack.zip \
  --api-url https://stor.listserv.online/api/packages  \
  --api-key $REFPACK_TOKEN
                
            
            
                Expects a JSON response like { "success": true, "message": "Package uploaded." } from the registry API.
                $REFPACK_TOKEN should be an API key obtained from your user account on this registry.
            
        

        
            5. Pull a Package from Registry
            Download a package ZIP from a registry:
            
                refpack pull \
  --id myid \
  --version 1.0.0 \
  --dest ./downloads/myid-1.0.0.refpack.zip \
  --api-url https://stor.listserv.online/api/packages
                
            
        

        
            6. Inspect Package Metadata
            Fetch and print the manifest (data.meta.json) for a specific package version from a registry:
            
                refpack meta \
  --id myid \
  --version 1.0.0 \
  --api-url https://stor.listserv.online/api/packages
                
            
        

        
            7. Example Workflow
            A complete example from scaffolding to inspecting metadata:
            
                # Scaffold a new package
refpack scaffold --output ./country-data --id country --title "Country Dataset" --author "Data Team"

# Pack and sign
refpack pack \
  --input ./country-data/ \
  --output country-1.0.0.refpack.zip \
  --sign-key ./country-data/sign-key.pem \
  --key-id $(cat ./country-data/key-id.txt)

# Validate locally
refpack validate \
  --package country-1.0.0.refpack.zip \
  --verbose # Optional

# Push to this registry
refpack push \
  --package country-1.0.0.refpack.zip \
  --api-url https://stor.listserv.online/api/packages \
  --api-key $YOUR_API_KEY_HERE 

# Pull from this registry
refpack pull \
  --id country \
  --version 1.0.0 \
  --dest ./downloads/country-1.0.0.refpack.zip \
  --api-url https://stor.listserv.online/api/packages

# Inspect metadata from this registry
refpack meta \
  --id country \
  --version 1.0.0 \
  --api-url https://stor.listserv.online/api/packages
                
            
        

        
            Notes
            
                All commands can be run with node refpack.js ... or, if the CLI is installed globally (e.g., via npm), with refpack ....
                On Windows, use type instead of cat to read files into command arguments: --key-id $(type .\my-refpack\key-id.txt) (or use PowerShell equivalent Get-Content).
                The scaffold command generates a new RSA private key (sign-key.pem) and a simple key ID (key-id.txt) for convenience. In production, manage your keys securely.
                Always validate your RefPack locally using refpack validate before pushing to a registry to catch issues early.
                For pushing to this specific RefPack Gallery, the --api-url should point to its API endpoint (e.g., https://stor.listserv.online/api/packages). You will need an API key from your account settings on this gallery.