huly-cli — AI-agent-first CLI for self-hosted Huly.

Drive your Huly workspace from any AI agent. Automate issues, projects, channels, docs, calendar & time tracking — no browser, no MCP, no Playwright.

---

Install

# Preferred — legacy canonical name
npm i -g @iamcoder18/huly-cli

# New name — same tarball, also maintained
npm i -g @huly-cli/cli

huly --version

Other package managers:

pnpm add -g @iamcoder18/huly-cli   # or @huly-cli/cli
yarn global add @iamcoder18/huly-cli   # or @huly-cli/cli
bun add -g @iamcoder18/huly-cli   # or @huly-cli/cli

Or try it without installing:

npx @iamcoder18/huly-cli --version
# or
npx @huly-cli/cli --version

To build from source, see Development.

---

Agent Skill (AI coding agents / OpenClaw)

The CLI ships a drop-in Agent Skill — a curated SKILL.md plus a references/ bundle that teaches an AI coding agent (or OpenClaw) how to drive your Huly workspace end-to-end without a browser.

# Any agent consuming the open `skills` package format
npx skills add IamCoder18/huly-cli

# OpenClaw
openclaw skills install @iamcoder18/huly

The install gives the agent the skill's SKILL.md and references/*.md so it can pick the correct surface on the first try. See Getting started — Agent Skill for verification and the canonical skill source path.

---

Why huly-cli (not the MCP wrappers)

	huly-cli	MCP-based wrappers
Talks to Huly via	Direct SDK (no separate MCP server or runtime)	huly-mcp process + JSON-RPC
Browser / Playwright	None — fully headless	Often required for auth/UI flows
Employee / user creation	Works (including the fields MCP stops at)	Often half-implemented
Time tracking / calendar recurrence	First-class (durations, recurring rules)	Frequently missing or stubbed
Output formats	table, json, jsonl, markdown — same flags everywhere	Varies per wrapper
Agent install	npx skills add IamCoder18/huly-cli (one command)	Manual MCP server config
Polish	Every command has --yes, --json, idempotency, ref-resolution	Inconsistent

Manually verified against every Huly product area — accounts, workspaces, Tracker (projects, issues, components, milestones, templates), Collaboration (channels, DMs, threads, comments, activity), Knowledge (cards, documents, master-tags, teamspaces), Planning (actions, scheduling, time tracking), Calendar (events, recurrence), Platform (spaces, types, relations, approvals, notifications).

---

Quickstart

# 1. Write your config (dotenv format — KEY=value, NO `export` prefix)
mkdir -p ~/.config/huly
cat > ~/.config/huly/.env <<'EOF'
HULY_URL=https://huly.example.com
HULY_EMAIL=you@example.com
HULY_PASSWORD=your-password
EOF

# 2. Create an account + first workspace (skip if you already have one)
#    The CLI reads HULY_PASSWORD from the dotenv file automatically.
huly signup --email you@example.com --password "$HULY_PASSWORD" \
            --first You --last Name --create-workspace my-ws --yes

# 3. Log in
huly login --headless

# 4. Create a project + first issue
huly project create --name "Demo" --identifier DEMO
huly issue  create --project DEMO --title "Set up CI pipeline" --yes

# 5. Create a Planner todo + schedule it (note: --start and --duration are required)
huly action    create --title "Implement login screen" --owner you@example.com --yes
huly action    list --assignee you@example.com --completed false
huly action    schedule <ref> --start "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --duration 30

Want the full narrative? See Getting started and the Bootstrap a new project workflow.

---

Documentation

Onboarding

• Getting started — config files, auth modes, signup, the Agent Skill, troubleshooting first-run
• Usage — global flags, output modes, ref resolution, writing markup correctly
• Security — what the CLI does and doesn't do, credential storage, threat model

Command reference

• Accounts & workspaces — login, signup, whoami, workspace, user
• Tracker — project, issue, component, milestone, issue-template
• Collaboration — comment, channel, dm, thread, activity
• Knowledge — card, card-space, master-tag, document, teamspace
• Planning — action, schedule, time
• Calendar — calendar, recurring events
• Platform — space, space-type, association, relation, project-type, task-type, issue-status, notification, approval

Guides

• Workflows — bootstrap a project, bulk-archive, daily report, copy issues between projects, orphan cleanup
• Migration — from huly-mcp, the SDK, the REST API, or the web UI

Reference

• CLI behavior — smart defaults, caches, filtering, idempotency, error exits, prompts, pooling
• Platform behavior — cascades, triggers, permissions, integrations, calendar quirks, locking
• Environment variables — every HULY_* var, credential file locations, reset recipe
• Model surface — class ID reference and plugin/surface map

Advanced

• Escape hatches — huly api and huly ws for raw RPCs
• CLI architecture — source layout, connection flow, markup handling
• Server architecture — services, database, transactions, backups, upgrades

Contributing

• Development — conventions, adding a new command, build commands

---

License

GNU Affero General Public License v3.0 or later — see LICENSE.