Hence Share

Install from your project root directory. Running npx skills add from a subdirectory will install into the wrong location.

Package and publish a project to the Hence gallery with screenshots, metadata, and attribution.

Workflow

1. Authenticate

Check for existing credentials. If none found, start the device flow:

python scripts/auth.py --check

If the check fails, run the device flow:

python scripts/auth.py

The script will print a URL and a one-time code. Before running the command, tell the user they'll need to:

1. Open the URL in their browser
2. Log in to Hence if they aren't already (via GitHub or Google)
3. Enter the code shown in the terminal

The script will wait and automatically complete once the user approves. No further action is needed from the agent after that.

2. Gather metadata

Fetch valid slugs before assembling the project:

python scripts/fetch_metadata.py topics
python scripts/fetch_metadata.py agents
python scripts/fetch_metadata.py models

Pass --json for raw JSON when further processing is needed. See references/api.md for response schemas.

Ask the user:

• Which topics fit their project (pick from the list)
• Which agent and model they used (pick from the lists)
• A title, one-liner pitch, and optionally a backstory for the description

3. Capture screenshots

Up to 5 screenshots (1 primary + 4 additional).

For web apps — use the capture script:

python scripts/capture.py http://localhost:3000 --output hero.png
python scripts/capture.py http://localhost:3000/features --output features.png

For non-web projects — ask the user for screenshot file paths.

4. Share

python scripts/share.py \
  --title "My Project" \
  --one-liner "A short pitch" \
  --description "The backstory..." \
  --screenshot hero.png:"Hero view" \
  --screenshot features.png:"Feature tour" \
  --topics '["cli", "productivity"]' \
  --agents '[{"slug": "claude_code", "model_slug": "claude-sonnet-4"}]' \
  --url "https://myproject.dev"

Use path:Caption text format for --screenshot to attach a caption (split on first colon). Omit the colon for no caption.

The script shows a review summary and asks for confirmation before uploading.

Pass --yes to skip the confirmation prompt when running non-interactively.

5. Update an existing project

python scripts/update.py <project-id> \
  --title "New Title" \
  --one-liner "Updated pitch" \
  --yes

To manage screenshots on an existing project, use screenshots.py (see step 6).

6. Manage screenshots on an existing project

# List all screenshots with IDs and captions
python scripts/screenshots.py <project-id> list

# Add a screenshot
python scripts/screenshots.py <project-id> add --file hero.png --caption "Hero view"

# Update caption or image
python scripts/screenshots.py <project-id> update <screenshot-id> --caption "New caption"
python scripts/screenshots.py <project-id> update <screenshot-id> --file new.png

# Remove a screenshot
python scripts/screenshots.py <project-id> remove <screenshot-id>

# Reorder (pass all IDs in desired order; first becomes primary)
python scripts/screenshots.py <project-id> reorder <id1> <id2> <id3>

7. Inspired-by linking

If the user found inspiration via hence-search and you stored a project ID with save_memory, include it:

python scripts/share.py ... --inspired-by <project-id>

CLI Reference

capture.py

python scripts/capture.py <url> [--output <file>] [--wait <ms>]

share.py

update.py

screenshots.py

python scripts/screenshots.py <project_id> <subcommand> [options]

API details

See references/api.md for full endpoint documentation, field formats, and error codes.