huly-cli

Python CLI for interacting with a Huly workspace from the terminal.

Features

Full CRUD support for the core Huly entities:

Additional capabilities:

• Issue descriptions & document content: read and write rich-text content via the Collaborator RPC. Markdown is converted to/from ProseMirror JSON automatically.
• Issue fields: priority, status, assignee, due date, component, and labels (repeatable --label flag on create/update)
• Status filtering: issues list --status <name> resolves against the live workspace status index, supporting custom statuses
• Fulltext search: huly search "query" searches titles and body content across every class in the workspace, with optional --class filters and a class-scoped wrapper at huly issues search.
• JSON mode: huly --json <command> for machine-readable output
• Full IDs in tables: id and parent columns in list output never truncate to … — values are always copy-pasteable into subsequent commands
• Agent-friendly markdown: huly documents describe DOC_ID --markdown emits plain GFM with no Rich box or reflow
• Self-upgrade: huly upgrade to update from PyPI
• Shell completion: huly --install-completion

Prerequisites

• Python 3.11+
• uv (only needed for source-checkout development)
• A Huly account with access to the target workspace

Install

Option 1: Install from PyPI

The package name is huly-cli. The executable is huly.

Recommended: pipx (standalone CLI install)

pipx creates an isolated environment per tool and puts the executable on PATH automatically.

pipx install huly-cli
huly --help

Upgrade:

pipx upgrade huly-cli
# or: huly upgrade

Alternative: pip (virtualenv or CI)

pip install huly-cli

Option 2: Use from a source checkout

1. Install dependencies, including dev tools:

uv sync --extra dev

2. Copy the example environment file:

cp .env.example .env

3. Edit .env with at least:

• HULY_URL
• HULY_WORKSPACE

4. Run commands with uv run huly instead of huly.

Environment Variables

The CLI loads config in this order:

1. CLI flags (--url, --workspace)
2. Environment variables
3. .env in the current directory
4. ~/.config/huly/config.toml

Supported variables:

• HULY_URL
• HULY_WORKSPACE
• HULY_EMAIL
• HULY_PASSWORD

Auth cache location:

• Config: ~/.config/huly/config.toml
• Tokens: ~/.config/huly/auth.json

The token cache is reused automatically. If the cached token expires, the CLI needs HULY_EMAIL and HULY_PASSWORD available to re-authenticate.

Login

Source checkout? Replace huly below with uv run huly.

Interactive login

huly --url https://huly.example.com --workspace my-ws auth login

You will be prompted for email and password. Then confirm:

huly auth status

Login using .env

Put all four values in .env:

HULY_URL=https://huly.example.com
HULY_WORKSPACE=my-ws
HULY_EMAIL=you@example.com
HULY_PASSWORD=your-password

Then run:

huly auth login
huly auth status

Usage Examples

Projects

huly projects list
huly projects get DEMO

Issues

# List and filter
huly issues list --project DEMO --limit 10
huly issues list --status backlog --assignee john

# Create
huly issues create --project DEMO --title "Fix login bug" \
  --priority high --status todo --assignee "Jane" \
  --due-date 2025-06-01 --component "Auth" --label "bug"

# Update
huly issues update DEMO-1 --status done --priority low
huly issues update DEMO-1 --due-date 2025-07-01 --component "API"
huly issues update DEMO-1 --label "sprint-3"

# Read/write descriptions
huly issues describe DEMO-1
huly issues describe DEMO-1 --set "## Updated description"
huly issues describe DEMO-1 --set-file ./description.md
huly issues describe DEMO-1 --raw  # show ProseMirror JSON

# Delete
huly issues delete DEMO-1

Documents

# List and filter
huly documents list --space "Engineering"
huly documents list --title-contains "RAG"       # case-insensitive substring
huly documents list --parent DOC_ID              # direct children only

# Find a doc without knowing its ID
huly documents search "rag template"             # alias for --title-contains
huly documents get --title "Design Doc"          # errors if title is ambiguous
huly documents describe --title "Design Doc"

# Create / update / describe / delete by ID
huly documents create --space "Engineering" --title "Design Doc"

# Read content
huly documents describe DOC_ID              # rendered markdown in a Rich panel
huly documents describe DOC_ID --markdown   # plain GFM to stdout — safe to pipe, diff, or feed back into --set-file
huly documents describe DOC_ID --raw        # raw ProseMirror JSON

# Write content
huly documents describe DOC_ID --set "# Design\n\nContent here."
huly documents describe DOC_ID --set-file ./doc.md

huly documents update DOC_ID --title "Updated Title"
huly documents duplicate DOC_ID --title "Weekly Status — 2026-04-19"
huly documents delete DOC_ID

# Hierarchical view via the parent field
huly documents tree                             # every space, grouped
huly documents tree --space "Engineering"       # one teamspace
huly documents tree --root DOC_ID               # subtree under one doc
huly documents tree --depth 2                   # cap recursion
huly --json documents tree                      # nested JSON output

documents duplicate copies a source document into a new one in a single command — useful for instantiating template-style docs. It inherits the source's space and parent by default; pass --space or --parent to override.

Markdown tables (| a | b |\n| --- | --- |\n| 1 | 2 |) round-trip through documents describe --set / --set-file — they are stored as real ProseMirror table / tableRow / tableHeader / tableCell nodes, not literal pipe characters, and the Huly UI renders them as styled tables.

For ProseMirror features the markdown parser does not cover (colspan, rowspan, custom node types), pass raw ProseMirror JSON directly:

# Inline JSON
huly documents describe DOC_ID --set-raw '{"type":"doc","content":[...]}'

# From a file
huly documents describe DOC_ID --set-raw-file ./doc.pm.json

The four write flags (--set, --set-file, --set-raw, --set-raw-file) are mutually exclusive; invalid JSON or a non-doc root is rejected before any network IO.

--markdown is the preferred read path for agents: no Rich box, no reflow, no ellipsis truncation, and the output round-trips cleanly back into --set-file. --raw and --markdown are mutually exclusive.

Components

huly components list --project DEMO
huly components create --project DEMO --label "Auth Service" --description "Handles auth"
huly components update COMP_ID --label "Renamed" --description "Updated"
huly components delete COMP_ID

Milestones

huly milestones list --project DEMO
huly milestones create --project DEMO --label "v1.0" --status planned --target-date 2025-06-01
huly milestones update MS_ID --status completed
huly milestones delete MS_ID

Labels

huly labels list
huly labels create --title "bug" --color 1
huly labels update LABEL_ID --title "critical-bug"
huly labels delete LABEL_ID

Templates

huly templates list --project DEMO
huly templates get TEMPLATE_ID
huly templates describe TEMPLATE_ID
huly templates describe TEMPLATE_ID --set "## Template description"

Members

huly members list

Search

# Fulltext search across every class in the workspace.
huly search "milestone 3"

# Limit results and filter client-side by fully qualified class.
huly search "roadmap" --limit 10 --class tracker:class:Issue
huly search "onboarding" --class document:class:Document --class tracker:class:Issue

# Class-scoped wrapper for issues.
huly issues search "login bug"

# JSON output for scripting.
huly --json search "project" --limit 5
huly search "project" --limit 5 --json

Notes:

• The --class filter is applied client-side on the returned doc._class; the server's equivalent query parameter is not reliable.
• Results are ranked by descending relevance score. Omitting --class returns a mixed result set across issues, documents, templates, etc.

JSON mode

huly --json projects list
huly --json issues list --project DEMO --limit 5
huly --json issues describe DEMO-1

Smoke Testing

The repo includes an automated smoke runner:

uv run python scripts/live_smoke.py                  # read-only checks
uv run python scripts/live_smoke.py --allow-writes    # CRUD checks with cleanup

Local Test Suite

uv run --extra dev pytest -q

Packaging and PyPI

The package is published on PyPI as huly-cli.

pipx install huly-cli

Or with pip in a virtualenv or CI:

pip install huly-cli

For the maintainer release checklist, see RELEASE.md.

CLI Help

huly --help
huly issues --help
huly issues create --help

License

MIT