The terminal client

The hania command is a coding chat in your terminal. Run it in a project folder and it works with an agent on that folder: reading and editing files, searching, and running commands. Changes are shown to you for approval first, unless the agent is set to run them without asking.

Install

On macOS, Linux and WSL:

curl -fsSL https://app.hania.ai/install.sh | bash

On Windows, in PowerShell:

irm https://app.hania.ai/install.ps1 | iex

On macOS, Linux and WSL, the installer puts the binary at ~/.hania/bin/hania and doesn't change any of your shell files. If that folder isn't on your PATH yet, it prints two commands that add it for your shell. On zsh they look like this:

echo 'export PATH="$HOME/.hania/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

On bash it uses ~/.bashrc on Linux and ~/.bash_profile on macOS (or ~/.bash_login or ~/.profile, if that's the one you have). For any other shell it prints the export PATH=… line for you to add yourself. Until you run them, use the full path ~/.hania/bin/hania.

On Windows, the installer puts the binary in %USERPROFILE%\.hania\bin and adds that folder to your PATH itself, so hania works straight away in the PowerShell window you installed from. Windows that were already open, such as other PowerShell, cmd or Windows Terminal tabs, don't see it until you open them again. If the installer stops with a red error, it installed nothing, and the message says why.

You can also download the binary directly from https://app.hania.ai/install/hania-code/<os>/<arch>, where os is linux, darwin, or windows and arch is amd64 or arm64. On Windows the file downloads as hania.exe. The SHA-256 checksums of these files are at https://app.hania.ai/install/SHA256SUMS. A few things to know:

• On macOS and Linux, a downloaded file won't run until you make it executable with chmod +x hania.
• The macOS builds aren't notarized, so macOS will most likely block a file downloaded in a browser. Use the install command instead - it isn't affected.

The client keeps itself current: on launch it checks for a newer build in the background. While it downloads, the footer shows Auto-updating…, and when it's done it shows ✓ update installed · restart to apply. hania selfupdate (or hania update) checks straight away and tells you whether you're already up to date, the update is installed, or a newer build couldn't be installed here, with a link to download it.

On Windows this works the same when you installed with the PowerShell command: the new build is used the next time you start hania. A hania.exe you downloaded yourself never updates itself, and hania selfupdate tells you to run the install command. Running the install command again is always a safe way to update; when you already have the newest build it changes nothing.

Sign in

On first run, hania asks for an API key. Use a management key - it starts with hania_sk_ and you create it under API keys in the console. The client checks the key by listing your agents, then saves it. hania login asks for a key again whenever you want to change it, and hania logout (or /logout in a session) clears the stored key, so the next launch asks for one.

Give the key these abilities. The sign-in prompt lists them too.

Your computer

After you sign in, the next time hania starts it registers this computer with your workspace. It then appears on the Machines page, and there is nothing to pair or paste. Each computer counts toward your plan's machine limit. On Free, registration is refused and hania tells you that Hania Code on your computer needs a paid plan, which you can upgrade to in the console under Billing. The chat stays open, so you can keep talking to the agent, but it can't work on your files or run commands. See plan limits.

The computer is connected to Hania while hania is open. To keep continuing your chats in the console after you close it, run hania runner. See Computers.

Commands

The working folder

The agent works in the folder you started hania from. Every message you send tells Hania which computer and folder you are in, so the conversation always works where you are.

Sessions and resume

Each launch is its own session with its own conversation, so closing the terminal never loses work on Hania's side - the transcript lives on the server. Type /resume to see the last 20 sessions you had with the current agent from this install of hania, and continue one where it left off.

• Another folder. If you resume a session from a different folder on the same computer, the conversation moves to the new folder from your next message.
• Another computer. Each install keeps its own identity in ~/.hania/config.json, so /resume on a second computer won't list sessions started on the first. Signing out doesn't change that identity.
• In the console. You can open the same conversation in the console and keep going there, approvals included, while hania or hania runner is running on that computer.

Rollback

Press Esc twice to open a list of this session's prompts. Pick one, then choose what to restore:

• Restore code and conversation - files go back to how they were at that point, and the conversation is cut back to match, so the agent's memory and your working tree agree again.
• Restore code - files go back, the conversation stays as it is.
• Restore conversation - the conversation is cut back, the files stay as they are.
• Never mind - close the list without changing anything.

The two options that restore code only appear when that point actually has file changes to undo.

How it works: before each write, edit, or patch, hania saves the file's previous state on your computer, under ~/.hania/file-history/. Rolling back uses those copies, not your git history. A few things to know:

• Changes made by shell commands aren't tracked, so they can't be rolled back.
• Files reached through a symbolic or hard link aren't restored.
• Copies are kept for the last 100 prompts, and removed 30 days after the newest one.
• File changes belong to the computer that made them. Restoring them needs that computer online; if it isn't, nothing is restored.

Slash commands

Type / and a menu of commands appears; arrow through it, or keep typing to filter, and Tab completes.

Menus in the client work with the up and down arrows and Enter, not by typing a number.

Goals

A goal is a finish line for the current chat. The agent keeps working, and each reply is checked against it, until it's met, can't be done, or you clear it. How goals behave in general is explained in goals for one conversation. In the terminal:

• /goal <what done looks like> sets it, and the agent starts on it straight away.
• /goal on its own shows the goal, how long it has been running, how many replies have been checked, the tokens used, and the latest reason.
• /goal clear clears it. stop, off, reset, none and cancel work too, and so do /clear and /new.
• /resume brings an active goal back with the session and starts its counters again. There is no /goal resume.

While a goal is active, the footer shows ◎ /goal active and how long it has been running, and each verdict appears in the chat as a line starting with ◎ goal.

One-off mode works too. hania -p "/goal …" keeps going until the goal ends. It exits with 0 when the goal is achieved. Otherwise it exits with a non-zero code and prints the reason, for example that the goal paused, was handed back to you, or can't be done. Ctrl+C stops it cleanly, and stops its background commands first.

The goal relies on this terminal. While the terminal is closed or disconnected, no goal replies start, so there are no retries and no check-ins. The goal stays set, and your next message carries it on. Closing the terminal, /logout, Ctrl+C in one-off mode, or stopping the runner also stops any commands running in the background. The chat is told which ones stopped and why, and the agent waits for you.

Modes

Press Shift+Tab, or type /mode, to change how much the agent does without asking: manual, accept edits, plan, or auto. What each one means is in Hania Code settings.

The mode you pick here applies to this chat and overrides the agent's own setting for it. Other chats with the same agent are unaffected, and the console shows which mode a chat is in without being able to change it.

Approvals

When the agent wants to write a file, edit one, apply a patch, or run a command, the change appears in the chat - edits as a diff, commands as the command line - and a card offers four choices:

• Approve - run it.
• Approve and don't ask again this session - run it and answer the rest of this session's cards automatically.
• Deny - don't run it.
• Deny and tell Hania what to do differently - don't run it, and give the agent a correction to work from.

Esc means deny. /auto toggles the do-not-ask mode on and off at any time.

While the agent works

A status line shows an animated mark, the word Generating, the elapsed time, a running estimate of output tokens, reasoning time when the model is thinking, and esc to interrupt. Pressing Esc stops the current turn and keeps the session, so you can redirect the agent without starting over.

You can keep typing while the agent works. When you press Enter, your message is queued: it shows dimmed above the prompt, marked queued (↑ to edit). If you queue more than three, the list ends with a count of how many more are waiting.

The agent reads a queued message after its current step, such as finishing a command or a file edit, and takes it into account for the rest of the same reply. That's when the message moves into the chat. If the reply ends before the agent gets to it, the message is sent as your next one instead, one per reply.

• Esc stops the agent and sends your queued messages straight away.
• ↑ on the first line of the prompt brings your queued messages back so you can edit them. They come back one per line, ahead of anything you've already typed.
• Slash commands you type while the agent works, such as /model, run after the reply has finished, in the order you typed them.
• Approvals. While the agent is waiting for an approval, queued messages wait too. A queued message never answers or approves anything.
• Errors. If the reply ends with an error, your queued messages go back into the prompt and aren't sent.

Multi-line input

End a line with a backslash and press Enter to start a new line instead of sending. The buffered lines stack above the input box while you write. Esc discards them. The next Enter without a trailing backslash sends the whole message.

Diffs

Proposed edits render as a diff with a file header, line numbers, and a highlighted background on added and removed lines, so a change is readable at a glance before you approve it.