easy8-cli

                                   ┌─────────┐
███████╗ █████╗ ███████╗██╗   ██╗  │ ███████ │
██╔════╝██╔══██╗██╔════╝╚██╗ ██╔╝  │██     ██│
█████╗  ███████║███████╗ ╚████╔╝   │ ███████ │
██╔══╝  ██╔══██║╚════██║  ╚██╔╝    │██     ██│
███████╗██║  ██║███████║   ██║     │ ███████ │
╚══════╝╚═╝  ╚═╝╚══════╝   ╚═╝     └─────────┘

Small Go CLI for Easy8. Current scope: Issues and Product Backlog Items (PBIs).

Official website: https://easy8.com

Goals

• Create, show, list, search, and update issues.
• List, show, and update product backlog items.
• Provide JSON output for automation and skills.
• Stay small, fast, and easy to extend.

Requirements

• Easy8 API key
• Go 1.22+ (only if building from source)

Quick Start

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Easy8Com/easy8-cli/main/scripts/install.sh | bash
easy8 setup
easy8 issue list --limit 10

Windows (PowerShell)

irm https://raw.githubusercontent.com/Easy8Com/easy8-cli/main/scripts/install.ps1 | iex
easy8 setup
easy8 issue list --limit 10

The installers detect OS/architecture, download the matching binary from GitHub Releases, and verify SHA-256 checksums. If no release is published yet, use the source build option below.

Other installation methods

GitHub Release (manual):

1. Download the right binary from Releases.
2. Download checksums.txt from the same release and verify SHA-256.
3. Rename binary to easy8 (or easy8.exe) and move it to a directory on your PATH.

Build locally:

go build -o easy8 ./cmd/easy8

Build with version stamp:

go build -ldflags "-X easy8-cli/internal/cli.Version=0.1.6" -o easy8 ./cmd/easy8

Run

./easy8 issue list --limit 10

Or run without building from source:

go run ./cmd/easy8 issue list --limit 10

Configuration

Recommended (writes YAML config file):

easy8 setup

The interactive setup wizard asks whether to enable automatic daily updates and defaults to yes.

Non-interactive examples:

easy8 setup --non-interactive --global --base-url "https://demo.easy8.com" --api-key "<your-key>"
easy8 setup --non-interactive --local --base-url "https://demo.easy8.com" --api-key "<your-key>"
easy8 setup --non-interactive --global --base-url "https://demo.easy8.com" --api-key "<your-key>" --autoupdate

Config files:

• Global: ~/.config/easy8/config.yaml
• Local (project override): .easy8.yaml

Load priority (highest to lowest):

1. Environment variables
2. Local config .easy8.yaml
3. Global config ~/.config/easy8/config.yaml
4. Built-in defaults

Environment variables:

export EASY8_BASE_URL="https://demo.easy8.com"
export EASY8_API_KEY="<your-key>"
export EASY8_AUTOUPDATE=true

Optional default IDs (avoid repeating on every create):

export EASY8_DEFAULT_PROJECT_ID=1
export EASY8_DEFAULT_TRACKER_ID=1
export EASY8_DEFAULT_STATUS_ID=1
export EASY8_DEFAULT_PRIORITY_ID=1
export EASY8_DEFAULT_AUTHOR_ID=1
export EASY8_DEFAULT_ASSIGNED_TO_ID=1

You can also save these defaults through setup flags:

easy8 setup --non-interactive --global --base-url "https://demo.easy8.com" --api-key "<your-key>" --project-id 1 --tracker-id 1 --status-id 1 --priority-id 1 --author-id 1 --assigned-to-id 1

Invalid integer and boolean values produce a warning on stderr.

Automatic daily updates can be enabled with the setup wizard, easy8 setup --autoupdate, or EASY8_AUTOUPDATE=true. Use easy8 setup --autoupdate=false to disable it explicitly in non-interactive environments such as Docker images. When enabled, easy8 silently checks GitHub Releases at most once every 24 hours on normal command startup, verifies checksums.txt, and updates the current executable if a newer release exists. The daily check state is stored in ~/.config/easy8/update-state.yaml. Autoupdate is skipped for easy8 version, easy8 help, easy8 commands, easy8 update, and easy8 setup.

Usage

Agent skill (source of truth)

This repository contains bundled skills for agent-driven Easy8 workflows:

skills/easy8-cli/SKILL.md

The skills are agent-agnostic and can be used with OpenCode, Claude Code, and Codex-style workflows.

Sync all bundled skills into your global OpenCode skill directory:

easy8 skill sync --target opencode

Sync into the current repository instead:

easy8 skill sync --target opencode --local

Preview or list bundled skills:

easy8 skill sync --target opencode --dry-run
easy8 skill list

Install only the primary easy8-cli skill:

easy8 skill install --target opencode
easy8 skill install --target claude
easy8 skill install --target codex --local

Print embedded primary skill content:

easy8 skill

Examples of prompts:

fix issue #1234
fix pbi #42
find pbi onboarding

Typical command mapping used by the skill:

easy8 issue show 1234 --quiet
easy8 pbi show 42 --quiet
easy8 pbi list --q "onboarding" --quiet

If the installed skill is not visible immediately, restart the OpenCode session so the skill index reloads.

Show issue detail

easy8 issue show 123
easy8 issue show 123 --include journals,attachments
easy8 issue show 123 --json
easy8 issue show 123 --quiet
easy8 issue show --id 123  # legacy compatible form

List issues

easy8 issue list --limit 10 --sort "priority:desc,due_date"

Search issues (fulltext)

easy8 issue search --q "onboarding"

Search issues with filters

easy8 issue search --q "petr" --assignee-id 51 --status-id 2 --priority-id 3 --due-date 2024-01-10 --subject "Login" --task-type-id 1

Search issues with name lookups

easy8 issue search --q "petr" --assignee "Alice Doe" --status "New" --priority "High" --task-type "Task" --project "Project A"

Notes:

• For assignee, status, priority, task type, and project you can use either name or ID.
• Name lookups are resolved via /users.json, /issue_statuses.json, /enumerations/issue_priorities.json, /trackers.json, /projects.json.

Create issue

easy8 issue create \
  --subject "Fix onboarding" \
  --project-id 1 \
  --tracker-id 1 \
  --status-id 1 \
  --priority-id 1 \
  --author-id 1 \
  --assigned-to-id 2 \
  --description "Short summary" \
  --done-ratio 0

easy8 issue create \
  --subject "Fix onboarding" \
  --project-id 1 \
  --tracker-id 1 \
  --status-id 1 \
  --priority-id 1 \
  --author-id 1 \
  --assigned-to-id 2 \
  --attachment ./spec.pdf \
  --attachment-description "Specification" \
  --attachment ./build.log

Update issue

easy8 issue update 123 --status-id 5 --done-ratio 80
easy8 issue update 123 --attachment ./error.log
easy8 issue update 123 --attachment ./screenshot.png --attachment-description "Failure screenshot"
easy8 issue update --id 123 --status-id 5 --done-ratio 80  # legacy compatible form

--done-ratio must be between 0 and 100.

--attachment can be repeated.

--attachment-description is optional and applies to the immediately preceding --attachment.

--notes is optional for issue update, including attachment-only updates.

Product Backlog Items (PBIs)

List PBIs

easy8 pbi list --limit 10
easy8 pbi list --status to_do --board-id 17
easy8 pbi list --q "design" --author-id 51

Filters: --status (to_do, realization, done, deleted), --author-id, --board-id, --q (fulltext).

Show PBI detail

easy8 pbi show 42
easy8 pbi show 42 --json
easy8 pbi show 42 --quiet
easy8 pbi show --id 42  # legacy compatible form

Update PBI

easy8 pbi update 42 --status done
easy8 pbi update 42 --status done --json
easy8 pbi update 42 --name "New name" --estimate 5 --description "Details"
easy8 pbi update --id 42 --status done  # legacy compatible form

Updatable fields: --name, --description, --status, --estimate.

Version

easy8 version

Update CLI

easy8 update
easy8 update --json
easy8 update --quiet

easy8 update downloads the latest matching binary from GitHub Releases, verifies checksums.txt, and replaces the current executable path.

To enable a silent daily update check for normal commands:

easy8 setup --autoupdate

Auth helpers

easy8 auth status
easy8 auth login --api-key "<your-key>"
easy8 auth logout

For local auth in current repo:

easy8 auth login --api-key "<your-key>" --local
easy8 auth logout --local

Command catalog (for agents)

easy8 commands --json
easy8 commands --quiet

Machine readable output

Entity and helper commands support both machine modes:

• --json: envelope format (ok, data, summary, optional breadcrumbs/context)
• --quiet: raw API-shaped JSON data

easy8 issue list --json
easy8 issue list --quiet
easy8 issue show 123 --json
easy8 issue show 123 --quiet
easy8 pbi list --json
easy8 pbi list --quiet
easy8 pbi show 42 --json
easy8 pbi show 42 --quiet
easy8 update --json
easy8 update --quiet

Testing

Unit tests (always run after any change):

go test ./...

Integration tests (require a running Easy8 server):

EASY8_BASE_URL="https://demo.easy8.com" EASY8_API_KEY="<your-key>" go test -tags integration -v -timeout 600s ./internal/api/

Integration tests use the //go:build integration build tag and skip automatically when EASY8_BASE_URL / EASY8_API_KEY are not set.

Roadmap

• Additional entities (projects, users, time, etc.)
• Config profiles
• Convenience commands (quick create, templates)