huly-cli 0.1.5

CLI for Huly project management

huly-cli

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

Status

This repo is currently a Python typer CLI, not a Node or pnpm project.

It has been checked against hcengineering/platform@v0.6.504 and smoke-tested against https://huly.example.com workspace my-ws.

What is verified today:

• Authentication flow via /_accounts
• Read access for projects, issues, components, documents, templates, members, labels, and issue descriptions
• Live CRUD for issues, documents, components, and milestones on https://huly.example.com workspace my-ws
• Live template description update and restore flow
• Workspace-specific issue status display and status filtering
• Local unit/CLI test suite
• CI-equivalent local checks: uv sync --extra dev, uv run ruff check ., uv run ruff format --check ., uv run pytest tests/ -v, uv run python -m build, and uv run twine check dist/*

What is not fully verified yet:

• Automated live-workspace CI has not been added
• You should still prefer a disposable project or disposable teamspace for release-time live smoke tests

Known live compatibility gaps at the time of writing:

• No known read-path breakage remains from the v0.6.504 comparison and smoke tests
• No known CLI CRUD gap remains on the currently implemented issue, document, component, and milestone surfaces
• The test suite now patches auth correctly; it no longer depends on a developer's local cached login state

Compatibility Target

• Huly platform tag: v0.6.504
• Example workspace URL used during verification: https://huly.example.com/workbench/my-ws/tracker/PROJECT_ID/issues

Important distinction:

• my-ws is the workspace slug
• DEMO is the project identifier in that workspace

If you run huly issues list --project MY-WS, it will fail because MY-WS is not a project ID.

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

Use this if you only want the CLI and are not modifying the source.

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

Recommended: pipx (standalone CLI install)

pipx is the recommended installer for standalone Python CLI tools. It creates an isolated environment per tool, puts the executable on PATH automatically, and works out of the box on PEP 668 environments (including modern macOS with Homebrew-managed Python, where bare pip install is blocked with externally-managed-environment).

pipx install huly-cli
huly --help

Upgrade an existing install:

pipx upgrade huly-cli

Alternative: pip (virtualenv or CI)

Use pip if you are installing into an existing virtualenv or a controlled CI environment:

pip install huly-cli
huly --help

Upgrade an existing install:

pip install --upgrade huly-cli

If huly is not found after a user-site pip install, the install directory may not be on your PATH (e.g. ~/.local/bin on macOS/Linux or %APPDATA%\Python\PythonXY\Scripts on Windows). Either add that directory to PATH, or switch to pipx, which handles PATH automatically.

Option 2: Use from a source checkout

Use this if you are developing in this repository:

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. Choose one auth approach:

• Interactive login: preferred for local use
• Environment-based login: useful for non-interactive runs and token refresh

Environment Variables

The CLI loads config in this order:

1. CLI flags
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 in order to re-authenticate automatically.

Login Walkthrough

Source checkout? Replace huly below with uv run huly.

Option 1: Interactive login

This is the simplest flow if you are testing locally and do not want to keep your password in .env.

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

You will be prompted for:

• Email
• Password
• Workspace slug, if it was not passed on the command line or set in .env

Then confirm auth is valid:

huly auth status

Option 2: Login using .env

Put all four values in .env:

HULY_URL=https://huly.example.com
HULY_WORKSPACE=my-ws
HULY_EMAIL=[e-mail]
HULY_PASSWORD=your-password

Then run:

huly auth login
huly auth status

Agent Skill

This repo includes a Codex skill for agents that need to install or operate the CLI:

• skill path: skills/huly-cli
• explicit invocation: $huly-cli

If you want to install that skill into a Codex skills directory outside this repo, copy or symlink it into ${CODEX_HOME:-$HOME/.codex}/skills:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
ln -s "$(pwd)/skills/huly-cli" "${CODEX_HOME:-$HOME/.codex}/skills/huly-cli"

If you prefer a copy instead of a symlink:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/huly-cli "${CODEX_HOME:-$HOME/.codex}/skills/"

Hands-On Smoke Test

Source checkout? Replace huly below with uv run huly. The repo also has an automated smoke runner: uv run python scripts/live_smoke.py (add --allow-writes for CRUD checks with automatic cleanup).

1. Confirm auth:

huly auth status

2. List projects:

huly projects list

3. Inspect a project:

huly projects get DEMO

4. List a few issues from that project:

huly issues list --project DEMO --limit 5

5. Inspect one issue:

huly issues get DEMO-1

6. Read the issue description:

huly issues describe DEMO-1

7. List project components:

huly components list --project DEMO --limit 5

8. Inspect a component by internal ID:

huly components get COMPONENT_ID

9. List a few documents:

huly documents list --limit 5

10. List issue templates:

huly templates list --limit 5

11. Verify status filtering:

huly issues list --status backlog --limit 5

12. List workspace members:

huly members list

13. List labels:

huly labels list

JSON mode

If you want machine-readable output for quick inspection:

huly --json projects list
huly --json issues list --project DEMO --limit 5
huly --json auth status

Commands That Currently Need Caution

The CLI write paths were exercised live during verification, but you should still prefer a disposable project or disposable teamspace when doing release-time smoke tests against a real workspace.

Local Test Suite

Run the unit and CLI regression tests with:

uv run --extra dev pytest -q

Expected result at the time of verification:

• 155 passed

Packaging And PyPI

The package is published on PyPI as huly-cli.

Install it with pipx (recommended for end-users):

pipx install huly-cli

Or with pip (for virtualenvs or CI):

pip install huly-cli

The repo also builds a wheel and sdist cleanly and CI validates the distribution metadata.

For the maintainer release checklist and publisher configuration notes, see RELEASE.md.

CLI Help

Top-level help:

huly --help

Auth help:

huly auth login --help

License

MIT