# The nim CLI

nim is a command-line tool for Nimbalyst trackers. List, create, update, comment, archive, and import items from your shell, and pipe JSON out.

`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](https://nimbalyst.com/docs/task-management/overview/).

### Install and run

`nim` ships as an npm package. Install it globally:

```bash
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

```bash
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

```bash
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:

```bash
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.