> For the complete documentation index, see [llms.txt](https://docs.nimbalyst.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nimbalyst.com/task-management/nim-cli.md).

# The nim CLI

`nim` is a companion command-line tool for working with your trackers from the terminal. List, create, update, comment on, archive, and import items without leaving your shell, and pipe results as JSON into other tools.

### 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nimbalyst.com/task-management/nim-cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.