Skip to content
aha-appPublic

About

Aha! command line interface

Resources

Stars

1 star

Watchers

22 watching

Forks

Repository files navigation

aha-cli

Command line interface for working with Aha!.

Currently supported commands are for creating and managing extensions, to-dos, and features.

Usage

$ npm install -g aha-cli
$ aha auth:login
Authentication to Aha!...
$ aha extension:create
Create a new extension...
$ aha extension:install
Install the extension into your Aha! account...

Commands

aha auth:check

Check if the stored credentials work

USAGE
  $ aha auth:check [-s <value>]

FLAGS
  -s, --subdomain=<value>  Aha! subdomain to use for authentication

DESCRIPTION
  Check if the stored credentials work

See code: src/commands/auth/check.ts

aha auth:login

Login to Aha! and save credentials for other commands

USAGE
  $ aha auth:login [-s <value>] [--authServer <value>] [--browser <value>]

FLAGS
  -s, --subdomain=<value>  Aha! subdomain to use for authentication
  --authServer=<value>     [default: https://secure.aha.io] server to use for authentication
  --browser=<value>        browser to use for login, e.g. 'safari' or 'firefox'

DESCRIPTION
  Login to Aha! and save credentials for other commands
  Credentials are saved in ~/.netrc

See code: src/commands/auth/login.ts

aha extension:add-contribution

Add a contribution to an extension

USAGE
  $ aha extension:add-contribution [-s <value>]

FLAGS
  -s, --subdomain=<value>  Aha! subdomain to use for authentication

DESCRIPTION
  Add a contribution to an extension

See code: src/commands/extension/add-contribution.ts

aha extension:build

Build an extension into a zip file for ease of distribution

USAGE
  $ aha extension:build [-s <value>] [--noCache]

FLAGS
  -s, --subdomain=<value>  Aha! subdomain to use for authentication
  --noCache                skip cached http imports

DESCRIPTION
  Build an extension into a zip file for ease of distribution

See code: src/commands/extension/build.ts

aha extension:create

Create an example extension

USAGE
  $ aha extension:create [-s <value>]

FLAGS
  -s, --subdomain=<value>  Aha! subdomain to use for authentication

DESCRIPTION
  Create an example extension

See code: src/commands/extension/create.ts

aha extension:install

Install the extension from the current directory

USAGE
  $ aha extension:install [-s <value>] [--dumpCode] [--noCache]

FLAGS
  -s, --subdomain=<value>  Aha! subdomain to use for authentication
  --dumpCode               dump all code as it is uploaded
  --noCache                skip cached http imports

DESCRIPTION
  Install the extension from the current directory

See code: src/commands/extension/install.ts

aha extension:tail

Live tail extension logs

USAGE
  $ aha extension:tail [-s <value>]

FLAGS
  -s, --subdomain=<value>  Aha! subdomain to use for authentication

DESCRIPTION
  Live tail extension logs

See code: src/commands/extension/tail.ts

aha extension:uninstall

Uninstall the extension in the current directory

USAGE
  $ aha extension:uninstall [-s <value>]

FLAGS
  -s, --subdomain=<value>  Aha! subdomain to use for authentication

DESCRIPTION
  Uninstall the extension in the current directory

See code: src/commands/extension/uninstall.ts

aha extension:watch

Watch the current directory for changes and install the extension each time a file changes

USAGE
  $ aha extension:watch [-s <value>] [--noCache]

FLAGS
  -s, --subdomain=<value>  Aha! subdomain to use for authentication
  --noCache                skip cached http imports

DESCRIPTION
  Watch the current directory for changes and install the extension each time a file changes

See code: src/commands/extension/watch.ts

aha help [COMMANDS]

Display help for aha.

USAGE
  $ aha help [COMMANDS] [-n]

ARGUMENTS
  COMMANDS  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for aha.

See code: @oclif/plugin-help

Aha! app commands

Commands for working with records in an Aha! instance use space-separated syntax. Their shared interface and implementation patterns are defined in Command conventions. Authenticate with aha auth login, or use an API key from standard input:

$ aha auth login --with-token --url https://your-account.aha.io < /path/to/api-key

Credentials are saved in ~/.netrc. Use -s <subdomain> to select a saved account. For API-key login, use --subdomain <alias> to give another instance a distinct saved name (for example, acme-local). Login refuses to replace an alias belonging to a different instance.

To-dos

Create a to-do in My work, automatically assigned to yourself:

$ aha todo create --title "Review the release notes"
$ aha todo create -t "Review the release notes" -b "Check the examples" --due 2026-11-01

The title is prompted for when running interactively; scripts and --json mode must provide --title. The optional --body is plain text, and --due uses YYYY-MM-DD. The command prints the created to-do's URL.

List, view, edit, complete, reopen, or delete a to-do:

$ aha todo list
$ aha todo list --state completed --search "release notes"
$ aha todo list --state all --json
$ aha todo view PERSONAL-TODO-1
$ aha todo edit PERSONAL-TODO-1 --title "Review updated notes" --due 2026-11-02
$ aha todo complete PERSONAL-TODO-1
$ aha todo reopen PERSONAL-TODO-1
$ aha todo delete PERSONAL-TODO-1 --yes

The list includes all pages of to-dos assigned to you. --state accepts pending (the default), completed, or all, based on your assignment's status. --search matches text in the title. Individual commands accept a numeric ID or reference. view shows the description, due date, overall status, assignees, parent, and link.

edit changes only the supplied fields. Use --body "", --clear-due, or --clear-record to clear the description, due date, or parent link. complete and reopen update only your assignment; repeating either action reports when it is already in the requested state. delete removes the entire shared to-do and asks for confirmation unless --yes is supplied. Scripts must use --yes.

Assign users or link a to-do to a parent record when creating or editing it:

$ aha todo create -t "Review implementation" --assignee @me,123456789 --record DEMO-123 --record-type feature
$ aha todo edit PERSONAL-TODO-1 --add-assignee 123456789 --remove-assignee @me
$ aha todo edit PERSONAL-TODO-1 --record DEMO-123-1 --record-type requirement

Assignment options accept comma-separated numeric user IDs or @me. Create defaults to yourself; an explicit --assignee selects those users, and --unassigned creates without assignees. Edit adds or removes only the specified users, preserving other assignments and their states. Parent links require both --record (ID or reference) and --record-type (a v3 record type such as feature, requirement, release, or page).

All to-do commands accept --json: list returns an array of v3 records, record commands return one v3 record, and delete returns { "id": "…", "deleted": true }. JSON preserves v3 fields, including overall status and individual assignment states. Use -s <subdomain> to select an account when multiple accounts are saved; JSON mode does not prompt. JSON deletion requires --yes.

Colon-separated commands also work, for example aha todo:view and aha todo:edit.

Features

aha feature create, list, view, edit, and delete support both space-separated and colon-separated syntax. Select an account with -s and use --json for scripts. Interactive creation prompts for a missing title when JSON input is not supplied. Scripts and JSON mode require a title through flags or input, and deletion requires confirmation or --yes. Missing input and API permission/validation errors return a nonzero exit code; API v3 failures do not trigger a v1 retry.

aha feature create --workspace AK --title 'Improve CLI' --json -s big
aha feature create --release AK-R-179 --title 'Improve CLI' -s big
aha feature create --workspace AK -t 'Improve CLI' -b 'Check the examples' -s big
aha feature list --workspace AK --search CLI --json -s big
aha feature list --filters '{"eq[status.id]":"123"}' --fields default,status --json -s big
aha feature view AK-123 --fields default,description,requirements,comments --json -s big
aha feature edit AK-123 --release AK-R-179 --owner @me -s big
aha feature edit AK-123 --status 123 --type 456 --start-date 2026-10-30 -s big
aha feature delete AK-123 --yes --json -s big

Creation requires a title and exactly one workspace or release. A workspace uses its default release. Move an existing feature by selecting its new release. Use --title/-t for the title and --body/-b for a plain-text description. Workspace, release, team, iteration, epic, and initiative flags accept supported IDs/references and resolve references through API v3 before submitting ID fields. Workflow status/type and team status flags take IDs. The @me owner shortcut uses /api/v1/me because v3 has no current-user endpoint.

For full writable payloads, pass a record object through --input file.json or pipe it to --input -; omit the outer record envelope. JSON IDs must be strings to avoid precision loss. Do not supply a field through both JSON and a flag. --body is escaped as plain text, consistently with to-dos. Use --body "" to clear it, or supply HTML in the JSON description field. Use JSON null to clear nullable dates/associations.

printf '%s' '{"description":"<p>Details</p>","initial_estimate":5,"remaining_estimate":3,"tags":[{"name":"CLI"}],"goals":[{"reference_num":"AK-G-1"}],"key_results":[{"reference_num":"AK-KR-1"}],"custom_fields":{"your_field_key":"value"}}' |
  aha feature edit AK-123 --input - --json -s big

JSON input also exposes detailed estimates/work done, duration/progress/estimate sources, release phases, program increments, time codes, score facts, watchers, and the other writable feature fields in API v3. Collection changes use v3 patch semantics: omitted associations are untouched; use {"id":"123","_destroy":true} to remove a specific collection item. Read-only or unknown top-level fields are rejected locally. The server validates account-specific fields and permissions.

Lists follow every cursor page. Human output is a table; --json returns a bare array of records, consistently with to-dos (including [] for no matches). Use --per-page (1–200), --filters with documented API v3 filter keys/string values, and --fields for field selection. Choose one parent flag (--workspace or --release). --sort field and optional --descending use API sorting, which may cap total results. Truncation emits a warning on stderr without changing the JSON array shape; remove sorting to retrieve the entire collection. Embedded collections are independently capped by API v3. Any embedded has_more is preserved in JSON and warned about on stderr; a feature view does not imply that every nested requirement or comment was returned.

Requirements

Requirements follow the same command and output conventions as features and to-dos. Space-separated and colon-separated syntax both work:

aha requirement create --feature AK-123 --title "Add list command" --body "Details"
aha requirement list --feature AK-123 --json
aha requirement view AK-123-1
aha requirement edit AK-123-1 --owner @me --status 123 --position 2
aha requirement edit AK-123-1 --input changes.json --json
aha requirement delete AK-123-1 --yes

Creates require an explicit feature ID/reference and a title. Human output prints the new reference and URL. Select an account with -s/--subdomain. --body/-b accepts plain text; JSON description preserves HTML. --input accepts a writable record object from a file or - for stdin, without an outer record wrapper:

{
  "description": "<p>Updated details</p>",
  "initial_estimate": 2,
  "start_date": "2026-11-04",
  "tags": [{ "id": "123", "_destroy": true }],
  "custom_fields": { "example_key": "Value" }
}

Supported fields include description, owner/status, integer position, dates, estimates, team/team status, iteration, tags, and custom fields. IDs must be strings; team fields and time codes depend on account settings. Only supplied fields change. Tag items add/remove individual associations, leaving others untouched. Move a requirement with --feature; its parent cannot be null.

Lists return bare JSON arrays or aligned ID, STATE, TITLE tables, follow all cursor pages, and support --search, --filters, --fields, --sort, --descending, and --per-page, as features do. Capped embedded collections and truncated sorted results warn on stderr. Commands use API v3; --owner @me shares the documented v1 current-user lookup exception. Scripts never prompt; deletion requires --yes in JSON or noninteractive mode.

Epics

Epics follow the same command and output conventions as features and to-dos:

aha epic create --workspace AK --title "Improve onboarding" --body "Details"
aha epic list --release AK-R-179 --json
aha epic view AK-E-1
aha epic edit AK-E-1 --release AK-R-180 --owner @me
aha epic edit AK-E-1 --input changes.json --json
aha epic delete AK-E-1 --yes

Create in exactly one explicit workspace or release, using an ID or reference. --body accepts plain text; --input accepts a writable JSON record object from a file or - for stdin. Structured input supports dates, estimates, progress/score settings, teams, iterations, strategy associations, tags, watchers, and custom fields supported by v3. IDs must be strings. Edits change only supplied fields; collection patches preserve omitted associations. Move an epic with --release.

Lists support the feature filters, fields, sorting and pagination options, return bare JSON arrays, and use aligned tables for people. Views include associated features by default. Embedded feature collections may be capped: the CLI retains has_more, warns on stderr, and shows how to retrieve the full set:

aha feature list --filters '{"eq[epic.id]":"1234567890123456789"}' --json

Select an account with -s/--subdomain. All epic operations use API v3; --owner @me shares the existing v1 current-user lookup exception. Scripts never prompt, and deletion requires --yes outside interactive use.

Development

Building

Build the CLI package into a .tgz file:

$ npm pack

This runs the prepack script automatically, which cleans the lib/ directory, compiles TypeScript, and generates the oclif manifest. The output is a file like aha-cli-v1.17.0.tgz.

Testing a local build

You can test the packaged CLI locally without installing it globally using npx:

$ npx --yes --package aha-cli-v1.17.0.tgz aha extension:watch

Replace aha-cli-v1.17.0.tgz with the actual filename produced by npm pack. Any aha command can be used this way, for example:

$ npx --yes --package aha-cli-v1.17.0.tgz aha extension:build
$ npx --yes --package aha-cli-v1.17.0.tgz aha extension:install

Generating a binary executable

You can compile the CLI into a standalone executable for your current platform using Bun.

Install Bun: https://bun.com/docs/installation

Install dependencies:

bun install

Build the executable:

bun run build:bun

This produces a binary at:

dist/aha

You can test it directly:

./dist/aha --version

If you want to install it locally on your PATH:

sudo mv dist/aha /usr/local/bin/
aha --version

About

Aha! command line interface

Resources

Stars

1 star

Watchers

22 watching

Forks

Releases

Packages

Used by

Contributors

Languages