harness / harness/cli

Restructure --help text to separate global/verb flags from command flags

Open
#192 0 comments 0 reactions 1 assignee View on GitHub

@BlueLabelscotch is already working on this.

Since Sep 8, 2026.

Dominant language
Go
Stars
22
Forks
10
Avg merge
14h 28m
Merged PRs (30d)
54

Description

Here's an example:

List projects in an organization

Usage:
  harness list project [parentid] [flags]

Flags:
      --all              Fetch all pages (incompatible with --offset and --limit)
      --columns string   Columns to display by ID or expr, e.g. "name,org" or "+sparkline" or "Name:it.name"
      --count            Print total item count and exit (incompatible with --offset, --limit, --all)
      --format string    Output format: json, yaml, jsonl, table, csv, tsv
  -h, --help             help for project
      --json             Output as JSON (shorthand for --format json)
      --level string     Scope level: project, org, or account (overrides prefix on id)
      --limit int        Return at most N items
      --list-columns     Print available column IDs and exit (use with --columns to customize output)
      --no-headers       Suppress column headers (table/csv/tsv) and paging footer (table)
      --offset int       Skip the first N items (item-level)
  -o, --out string       Write output to file instead of stdout
      --raw              Output the full raw API response (only with --format json)
      --search string    Filter projects by name
      --ui               Launch interactive TUI (requires a TTY)
      --yaml             Output as YAML (shorthand for --format yaml)

Global Flags:
      --debug            Enable debug logging
      --org string       Harness org identifier (overrides profile default)
      --profile string   Auth profile to use
      --project string   Harness project identifier (overrides profile default)
      --timeout float    Command timeout in seconds (0 = no timeout, e.g. 1.5)

Framework flags like --all, --count, --format, --json, etc. are all getting mixed into the "Flags" section even though those are "Verb" or "Global" level flags. This is a mechanical problem due to us adding those flags on the final "command" itself (because some are optional or conditional). Even though they are conditional, the help should not group them in the generic "Flags" section because this makes it much harder to actually parse out which flags are specific to this command.

An AI Agent must read through all those flags even though the bulk of those are generic global flags that work the same across a whole class of commands/nouns.

We might also consider whether to even list global/verb level flags at all since it increases token usage. These flags could be documented on list --help or in the root help, and not duplicated on each command (this will need Agent testing to verify that it does not reduce AI's effectiveness).

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.