Metadata-Version: 2.4
Name: huly-cli
Version: 0.1.3
Summary: CLI for Huly project management
Project-URL: Homepage, https://github.com/teslakoile/huly-cli
Project-URL: Repository, https://github.com/teslakoile/huly-cli
Project-URL: Issues, https://github.com/teslakoile/huly-cli/issues
License: MIT License
        
        Copyright (c) 2026
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cli,huly,project-management
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: httpx<1.0,>=0.28.0
Requires-Dist: pydantic<3.0,>=2.10.0
Requires-Dist: python-dotenv<2.0,>=1.0.0
Requires-Dist: rich<14.0,>=13.9.0
Requires-Dist: tomli-w<2.0,>=1.1.0
Requires-Dist: typer<1.0,>=0.15.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.22.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: twine>=6.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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`](https://docs.astral.sh/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`](https://pipx.pypa.io/) 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`).

```bash
pipx install huly-cli
huly --help
```

Upgrade an existing install:

```bash
pipx upgrade huly-cli
```

#### Alternative: `pip` (virtualenv or CI)

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

```bash
pip install huly-cli
huly --help
```

Upgrade an existing install:

```bash
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:

```bash
uv sync --extra dev
```

2. Copy the example environment file:

```bash
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`.

```bash
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:

```bash
huly auth status
```

### Option 2: Login using `.env`

Put all four values in `.env`:

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

Then run:

```bash
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`:

```bash
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:

```bash
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:

```bash
huly auth status
```

2. List projects:

```bash
huly projects list
```

3. Inspect a project:

```bash
huly projects get DEMO
```

4. List a few issues from that project:

```bash
huly issues list --project DEMO --limit 5
```

5. Inspect one issue:

```bash
huly issues get DEMO-1
```

6. Read the issue description:

```bash
huly issues describe DEMO-1
```

7. List project components:

```bash
huly components list --project DEMO --limit 5
```

8. Inspect a component by internal ID:

```bash
huly components get COMPONENT_ID
```

9. List a few documents:

```bash
huly documents list --limit 5
```

10. List issue templates:

```bash
huly templates list --limit 5
```

11. Verify status filtering:

```bash
huly issues list --status backlog --limit 5
```

12. List workspace members:

```bash
huly members list
```

13. List labels:

```bash
huly labels list
```

### JSON mode

If you want machine-readable output for quick inspection:

```bash
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:

```bash
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):

```bash
pipx install huly-cli
```

Or with `pip` (for virtualenvs or CI):

```bash
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](RELEASE.md).

## CLI Help

Top-level help:

```bash
huly --help
```

Auth help:

```bash
huly auth login --help
```

## License

MIT
