dhub CLI Guide

dhub

Installation

uv tool install dhub-cli    # via uv (recommended)
pipx install dhub-cli       # via pipx

Command Overview

dhub login              Authenticate via GitHub
dhub logout             Remove stored token
dhub env                Show active environment, config path, API URL
dhub init [path]        Scaffold a new skill project
dhub publish [ref]      Publish skill(s) — from dir or git repo
dhub install org/skill  Install a skill from the registry
dhub uninstall org/skill  Remove a locally installed skill
dhub list               List all published skills
dhub delete org/skill   Delete skill versions from registry
dhub run org/skill      Run a locally installed skill
dhub ask "query"        Natural language skill search
dhub eval-report org/skill@version  View eval report
dhub logs [ref] [-f]    View or tail eval run logs
dhub org list           List your namespaces
dhub config default-org Set default namespace for publishing
dhub keys add <name>    Store an API key for evals
dhub keys list          List stored API key names
dhub keys remove <name> Remove a stored API key
dhub --version          Show CLI version

See

references/command_reference.md

Environments (Dev / Prod)

dhub supports two independent stacks controlled by

DHUB_ENV

prod

https://lfiaschi--api.modal.run

~/.dhub/config.prod.json

dev

https://lfiaschi--api-dev.modal.run

~/.dhub/config.dev.json

Always prefix commands with

DHUB_ENV=dev

DHUB_ENV=dev dhub login
DHUB_ENV=dev dhub list
DHUB_ENV=dev dhub publish

The

dhub env

Authentication

dhub uses GitHub Device Flow (OAuth2). Run

dhub login

1. dhub requests a device code from the server
2. You open

   https://github.com/login/device

   and enter the displayed code
3. dhub polls until you authorize (up to 5 minutes)
4. Token is saved to

   ~/.dhub/config.{env}.json

All subsequent commands use this token automatically. Run

dhub logout

You can override the API URL with

dhub login --api-url <url>

Publishing Workflow

Quick publish (auto-detect everything)

From a directory containing a valid SKILL.md:

dhub publish              # auto-detects org, name, bumps patch version
dhub publish --minor      # bump minor version instead
dhub publish --major      # bump major version
dhub publish --version 2.0.0  # explicit version

Explicit publish

dhub publish myorg/my-skill          # specify org/skill, auto-bump patch
dhub publish myorg/my-skill ./path   # specify path to skill directory

How auto-detection works

1. Skill name — read from

   name

   field in SKILL.md frontmatter
2. Organization — auto-detected if you belong to exactly one org. If you have multiple, specify explicitly:

   dhub publish myorg/my-skill

3. Version — fetches latest version from registry, bumps patch by default. First publish uses

   0.1.0

Argument disambiguation

The first positional argument is interpreted as:

• A path if it starts with

  .

  ,

  /

  ,

  ~

  , or is an existing directory
• An org/skill reference otherwise

So

dhub publish .

dhub publish myorg/skill

Safety grading

After publishing, the server runs safety checks and assigns a grade:

--allow-risky

If the skill has an

evals

dhub logs

What gets zipped

The publish command creates a zip of the skill directory, excluding:

• Hidden files (names starting with

  .

  )

• __pycache__/

  directories

Publishing from a Git Repository

You can pass a git URL directly to

dhub publish

dhub publish https://github.com/myorg/my-skills-repo
dhub publish git@github.com:myorg/my-skills-repo.git --ref v2.0
dhub publish https://github.com/myorg/repo --minor

The command detects that the argument is a git URL (HTTPS, SSH, or

.git

How discovery works

1. The repo is cloned (shallow clone with

   --depth 1

   )
2. All

   SKILL.md

   files are found recursively
3. Hidden directories (

   .git

   , etc.),

   node_modules

   , and

   __pycache__

   are skipped
4. Each

   SKILL.md

   is validated — only directories with valid frontmatter (name + description) are published
5. Skills are published one by one; failures don't stop the remaining skills

Git-specific options

• --ref

  — branch, tag, or commit to checkout (only valid with git URLs)

Installing Skills

dhub install myorg/my-skill                          # latest version
dhub install myorg/my-skill --version 1.2.0          # specific version
dhub install myorg/my-skill --agent claude-code        # install + link to Claude Code
dhub install myorg/my-skill --agent all                # link to all agents
dhub install myorg/my-skill --allow-risky             # allow Grade C skills

Where skills get installed

• Canonical path:

  ~/.dhub/skills/{org}/{skill}/

• Agent symlinks (when using

  --agent

  ):

--agent

claude-code

~/.claude/skills/{skill}

cursor

~/.cursor/skills/{skill}

codex

~/.codex/skills/{skill}

windsurf

~/.codeium/windsurf/skills/{skill}

gemini-cli

~/.gemini/skills/{skill}

github-copilot

~/.copilot/skills/{skill}

roo

~/.roo/skills/{skill}

opencode

~/.config/opencode/skills/{skill}

40+ agents supported. Run

dhub install org/skill --agent all

Symlinks point to the canonical

~/.dhub/skills/

After installation: load the skill immediately

When you install a skill on behalf of the user, always read it into the current conversation so it's usable right away. Don't tell the user to start a new session.

After

dhub install

1. Read the installed skill's

   SKILL.md

   from

   ~/.dhub/skills/{org}/{skill}/SKILL.md

2. Confirm to the user that the skill is loaded and ready to use now

Don't read reference files upfront — the SKILL.md itself will tell you when to consult specific references.

The user installed a skill because they want to use it — treat installation as implicit activation.

Integrity verification

Downloads are verified via SHA-256 checksum before extraction. If the checksum doesn't match, installation aborts.

Running Skills Locally

dhub run myorg/my-skill              # run the skill
dhub run myorg/my-skill -- --flag    # pass extra args to the entrypoint

Prerequisites

• The skill must be installed locally (

  dhub install

  first)
• The skill must have a

  runtime

  block in its SKILL.md

• uv

  must be available on PATH
• Required environment variables (from

  runtime.env

  ) must be set
• Only

  language: python

  is supported

What happens

1. Parses SKILL.md to get runtime config
2. Validates prerequisites (uv, lockfile, entrypoint, env vars)
3. Runs

   uv sync --directory {skill_dir}

   to install dependencies
4. Runs

   uv run --directory {skill_dir} python {entrypoint} [extra_args]

Eval Reports

View evaluation results for a published skill version:

dhub eval-report myorg/my-skill@1.0.0

The report shows:

• Agent used for the eval run
• Judge model that evaluated the output
• Status: passed, failed, error, pending
• Results: pass/fail count and per-case details with reasoning

Evals run automatically in the background after publishing a skill that has an

evals

dhub eval-report

Eval Logs (Real-Time Streaming)

Tail eval run logs in real-time, or view recent runs:

dhub logs                              # list recent eval runs
dhub logs myorg/my-skill --follow      # tail latest run for latest version
dhub logs myorg/my-skill@1.0.0 -f      # tail latest run for specific version
dhub logs <run-id> --follow            # tail a specific run by ID

When you publish a skill with evals, the CLI automatically attaches to the log stream. Press Ctrl-C to detach — you can re-attach later with

dhub logs

Events include: sandbox setup, agent stdout/stderr, judge start, case verdicts (PASS/FAIL), and a final summary.

API Key Management

Skills that use third-party APIs during evaluation need API keys stored in Decision Hub:

dhub keys add OPENAI_API_KEY        # prompts securely for the value
dhub keys list                      # show stored key names
dhub keys remove OPENAI_API_KEY     # delete a stored key

Keys are stored server-side (encrypted) and injected into eval sandbox environments. Key names must match the

runtime.env

Organization Management

dhub org list    # list namespaces you can publish to

Your namespaces are derived from your GitHub account and org memberships. Run

dhub login

Skill Discovery

dhub ask "analyze A/B test results"
dhub ask "generate presentation slides"

Natural language search across all published skills. Returns matching skills with descriptions and install instructions.

Scaffolding a New Skill

dhub init                  # interactive — prompts for name and description
dhub init ./my-skill       # create in a specific directory

Creates:

my-skill/
  SKILL.md     # frontmatter + body skeleton
  src/         # source code directory

SKILL.md Format (Quick Reference)

---
name: my-skill                 # 1-64 chars, lowercase + hyphens
description: What it does      # 1-1024 chars, triggers skill activation
license: MIT                   # optional
runtime:                       # optional — for executable skills
  language: python
  entrypoint: src/main.py
  env: [OPENAI_API_KEY]
  dependencies:
    package_manager: uv
    lockfile: uv.lock
evals:                         # optional — for testable skills
  agent: claude
  judge_model: claude-sonnet-4-5-20250929
---
System prompt for the agent goes here.

Troubleshooting

"Connection timed out" or slow first request

Modal cold starts take 30-60s. Retry after a minute. All dhub HTTP calls use 60s timeouts internally.

"No namespaces available"

Run

dhub login

"You have multiple namespaces"

Specify the org explicitly:

dhub publish myorg/my-skill

dhub publish

"Version X already exists"

Versions are immutable. Bump the version:

dhub publish --patch

--minor

--major

--version

"Rejected (Grade F)"

The skill failed safety checks. Review your SKILL.md and scripts for dangerous patterns (shell injection, credential exfiltration, etc.).

"Skill not installed" when running

Install first with

dhub install org/skill

dhub run org/skill

"This skill has no runtime configuration"

Only skills with a

runtime

dhub run

dhub run

"Checksum mismatch"

Download was corrupted. Retry

dhub install

Wrong environment

Check with

dhub env

DHUB_ENV=dev

DHUB_ENV=prod

Config file location

• Dev:

  ~/.dhub/config.dev.json

• Prod:

  ~/.dhub/config.prod.json

• Override API URL:

  DHUB_API_URL

  env var (highest priority)