nim is a companion command-line tool for working with your trackers from the terminal. Use it when you live in a shell or want to script against your items: list, create, update, comment on, archive, and import items without opening the app, and pipe results as JSON into other tools. For the tracker itself, see the Tracker Overview.

Install and run

nim ships as an npm package. Install it globally:

npm install -g @nimbalyst/cli

Then run commands as nim <noun> <verb>, for example nim tracker list. You can also run it without installing, with npx nim tracker list.

How it connects

nim finds your workspace and tracker data on its own:

When Nimbalyst is running, nim talks to the app (live mode), so writes go through the same path as the UI.
When the app is closed, nim reads your local tracker database directly. Reads work either way.

A few commands depend on the running app: importing from external sources, linking a live session, and defining or deleting a type. Open Nimbalyst before using those. If you work with more than one project, point nim at one with --workspace <path>.

Reading items

nim tracker list --type bug --status open --priority high
nim tracker list --where severity=critical --since 1d --json
nim tracker get NIM-123
nim tracker show NIM-123        # renders the body
nim tracker types              # list types; add "show <type>" for one schema

Common list filters: --type, --status (or the shortcuts open and closed), --priority, --owner me, --search, --since and --until, --tag, and --where field=value for anything else. Add --json for machine output, --csv --columns key,status,title for a table, or --quiet for just the IDs.

Creating, updating, and commenting

nim tracker create bug "Login times out" --priority high --tag auth --body-file repro.md
nim tracker update NIM-123 --status in-review --owner me
nim tracker update NIM-123 --unset owner
nim tracker comment NIM-123 "Repro confirmed on main"
nim tracker archive NIM-123
nim tracker unarchive NIM-123

create takes the type and a title, plus optional --status, --priority, --owner, --tag (repeatable), --label, --field key=value, --due, --progress, and --body or --body-file. update takes the same flags to change fields, plus --unset <field> to clear one.

Importing from external sources

With the app open, nim can pull items in from installed importers, such as GitHub issues:

nim tracker importers                                       # what is installed
nim tracker import search github-issues --repo owner/repo --state open
nim tracker import github-issues "owner/repo#42" --type bug

Output and scripting

Every read command supports --json, so you can pipe nim into other tools. nim status reports how it is connecting and which workspace it resolved. Set NIM_OWNER so --owner me resolves to you, or NIM_WORKSPACE to fix a default project. Run any command with --help for its full set of flags.