# Nana CLI

The `nana` command talks to the [server](https://nana.areshk.dev/docs/features/server.md) from a shell. It manages
projects, terminal sessions, worktrees, and server settings. No
desktop app is needed, so it also works on a Linux or macOS remote server and
over SSH.

Commands work with what the server owns: projects and sessions. Tabs, panes, and
workspaces belong to each app, so there are no commands for them. Browser tabs
are the exception: they live in the desktop app, and `nana browser` talks to
the app on this computer.

## Install

- **With the desktop app:** choose **Install Command Line Tool…** from the app
  menu. It adds the installation's `current` directory to your user `PATH`,
  keeping the CLI, server, and runtime DLLs together across updates.
- **On a remote server:** see [Getting started](https://nana.areshk.dev/docs/user-guide/getting-started.md#cli-and-server-only).

Reopen your terminal after installing the command-line tool. An older standalone
`nana.exe` earlier on `PATH` still takes precedence; remove that old copy if
`nana --version` does not match the installed app.

## Basics

```bash
nana .               # open this folder in the desktop app
nana project list    # list projects
nana --help          # all commands; nana <command> --help for details
```

- Commands start the server they use if it isn't running, including a remote
  one with `--host`. `nana server status` and `nana server stop` never start
  it.
- Management commands take `--json` for machine-readable output.
- Ending or discarding a session and deleting a project or worktree need
  `--yes`.
- A project can be named by its ID, its name if unique, or its folder.
- `--host <destination>` runs the command against the server on another
  computer. It must come first: `nana --host devbox project list`. See
  [Remote servers](https://nana.areshk.dev/docs/features/remote-servers.md).

## Commands

| Command | What it does |
| --- | --- |
| `nana` | Shows help. |
| `nana <folder>` | Opens the folder as a project in the desktop app. Fails over SSH or without the desktop app. |
| `nana server start\|status\|stop` | Starts, inspects, or stops the server. `stop` refuses while terminals run; add `--force` to end them. |
| `nana project list\|add\|rename\|set-color\|set-icon\|delete` | Manages projects. Deleting ends its terminals but keeps files on disk. |
| `nana session list\|create\|send\|send-keys\|read-screen\|history\|search\|wait\|end\|discard` | Creates terminals, sends input, reads output, and waits for text or exit. |
| `nana worktree list\|create\|checkout-pr\|register\|remove` | Manages Git worktree projects, including checking out pull requests. |
| `nana settings get\|set` | Reads or changes [server settings](https://nana.areshk.dev/docs/features/server.md#settings). |
| `nana activity list\|ack` | Reads or clears [AI agent](https://nana.areshk.dev/docs/features/ai-agents.md) activity. |
| `nana browser open\|list\|read\|click\|…` | Drives browser tabs in the desktop app on this computer. See [Browser control](#browser-control). |
| `nana exec <project> -- <program> [args]` | Runs a program in the project folder, without a shell. |
| `nana git`, `nana files` | Run raw server Git and file actions as JSON. Advanced; the JSON shape follows the protocol and may change. |
| `nana install-skills` | Installs the Nana CLI skill for the AI agents found in your home folder. `--dir <path>` adds another skills folder. |
| `nana stdio` | Joins stdin and stdout to the server. Used by `--host` over SSH; you don't run it yourself. |

## Sessions from a script

```bash
id=$(nana session create my-app)
nana session send "$id" "npm test"
nana session send-keys "$id" Enter
nana session read-screen "$id" --lines 20
nana session end "$id" --yes
```

- `send` types text without pressing Return. `send-keys` sends `Enter`, `Tab`,
  `Escape`, `Backspace`, `Ctrl+C`, `Ctrl+D`, or `Ctrl+Z`.
- `read-screen` returns the last visible rows. `history` and `search` page
  through scrollback as JSON.
- `--saved` reads a session's last saved screen, even after it ended.
- `end` stops the program and keeps its saved output. `discard` also deletes
  the output.
- Sessions created here outlive the command and appear in every app under
  **Existing Terminals**.
- Inside a Nana terminal, session commands default to that terminal, and
  `create` to its project.
- `create` can take a `--directory` and a command to run after `--`.
- `wait --text <text>` waits for text on the screen, and `wait --exit` for the
  shell to exit. Both give up after 30 seconds by default.

## Browser control

```bash
tab=$(nana browser open localhost:3000)
nana browser wait-for-navigation "$tab"
nana browser fill "$tab" "#email" "me@example.com"
nana browser click "$tab" "button[type=submit]"
nana browser wait "$tab" --text "Welcome"
nana browser read "$tab"
nana browser screenshot "$tab" | base64 -D > page.png
nana browser close "$tab"
```

- Browser commands need the desktop app and don't take `--host`. `open` starts
  the app if it isn't running.
- `open` prints the new tab's ID. Pass it to the other commands.
- `snapshot` lists a page's interactive elements, each with a selector for
  `click`, `fill`, or `type`.
- `nana browser --help` lists every command.

## Exit codes

`0` on success. On any error, `nana` prints `nana: <message>` to stderr and exits
with `1`, including when a program run with `nana exec` fails.

## Profiles

`NANA_DIR` points the CLI, and the server it starts, at another profile folder.
Use it to run a separate, throwaway server. See [Server](https://nana.areshk.dev/docs/features/server.md#files).