Before you start
- Install uuldana-cli, then install at least one provider and sign in to it the way you normally do.
- Run
uuldana providersand confirm your providers show as installed. - Optional: choose the order and a permission ceiling with a
config.json(Initial configuration), or choose the order with/agentonce the session is running. Without a file, uuldana-cli uses the agents it finds, and they ask before risky actions as they normally do.
1. Start in your project
Open a terminal in your project directory and run:
uuldanauuldana-cli starts the first agent that can run, and the provider’s own interface appears. Your keyboard is relayed to it unchanged, and resizing the terminal resizes the provider. Work as you normally would, and leave the way you normally do in that provider.
uuldana-cli uses the terminal’s alternate screen, like a full screen program, and gives your terminal back when you leave. A header stays at the top and always shows uuldana-cli, which agent is working, and any warning, such as “PERMISSIONS BYPASSED”. The agent’s screen is drawn below it, so an agent that clears or repaints its screen cannot remove the header. On a small terminal the header shrinks to one line, and below six rows it is left out.
uuldana-cli needs an interactive terminal. It exits with code 2 when input or output is redirected.
Scroll back
The mouse wheel scrolls the agent’s earlier output on uuldana-cli’s screen, and Shift+PageUp and Shift+PageDown do the same. The header says how many rows back you are, and any other key returns to the live screen. An agent that asks for the mouse itself, as some do, is sent the wheel and scrolls its own screen, as it would in a plain terminal.
Because uuldana-cli takes the mouse, selecting text needs Shift held down while you drag.
Typing and pasting
On Windows, Shift+Enter and Ctrl+Enter start a new line in the agent’s input without sending it. Ctrl+Backspace deletes the last word. Text you paste, including several lines, arrives as one paste, so the lines are not sent one by one. When the clipboard holds a picture, Ctrl+V offers it to an agent that takes pictures.
Choose which agent works
Type /agent on an empty line and press Enter. A menu opens inside the frame:
- Pick the agent that works first. Up and Down, a number, or Enter choose; Esc leaves without changing anything.
- Pick the one that takes over when the first reaches its limit, then the next. “No more” ends the picking, and the agents you did not pick keep their order behind the ones you did.
The order is saved to config.json, which is created if it does not exist. A file created this way lists only the order and has no permissions entry, so the default ceiling still applies. If you picked a different agent than the one running, the work moves to it now: the running agent is stopped gracefully and the new one gets the conversation pasted into its input box. Nothing is sent until you press Enter, so nothing is spent before you decide. See Context handoff.
/agent is recognized only when the whole line is /agent. A line edited with the cursor keys or completed with Tab goes to the agent untouched.
2. Continue the session later
After leaving the provider, return to the same project directory and run:
uuldana resumeThis continues the most recent session of the current directory. uuldana-cli rebuilds the session from its journal, even after a crash, and resumes the provider’s own native session by id when the provider supports it. See Sessions & resume.
When an agent reaches its usage limit
If the active provider prints its usage-limit message, uuldana-cli stops it gracefully and starts the next agent with the visible conversation as its first prompt. You do not press Ctrl+C or restart anything. See Automatic failover.
Optional: skip permission prompts for one run
uuldana --bypass-permissionsThis replaces the configured permission ceiling with “never ask, unrestricted filesystem, network allowed” for that run only. See Permission behavior.
Other commands
uuldana --help
uuldana --version