AI Agents CLI + Cuiar

If your agent has a shell, it has Cuiar.

macOS and Linux
--json on each command
Exit codes 0 to 9

Goose, OpenCode, Cline, Amp, Aider and plain shell scripts all run commands. cuiar exec gives one task to the Cuiar agent and prints one result.

With --json, the result is JSON, and the exit code says what happened. A script or an agent reads it and picks the next step.

Setup

Install, sign in, run.

The CLI controls the Cuiar app on the same computer. The app must be open and signed in.

Install

curl -fsSL https://cuiar.com/install.sh | sh

2
Sign in
On a server, in CI or in an agent sandbox, make a key with cuiar keys create and set CUIAR_API_KEY instead. App control with a key needs Pro or Team.
```
cuiar login
```

Run a task

cuiar exec --json "What is the title of example.com?"

Tell your agent

Add a short rule to your agent's instructions file.

To use a website, run: cuiar exec --json --workspace <name> "<task>".
Exit code 5 means the Cuiar app is not open. Ask me to open it.

Route

One command, one result, one exit code.

That is the simplest contract for a script or an agent. There is no session to keep and no protocol to speak.

Local MCPcuiar mcp: Works; cuiar mcp, for an agent that prefers MCP.
CLIcuiar exec: Best fit; cuiar exec --json for one result, cuiar run to follow a long task.
REST APIapi.cuiar.com/v1: Works; POST /v1/tasks for CI with no CLI. Pro and Team.
Routineson a schedule: Works; cuiar routines create keeps the schedule in the Cuiar app. Your crontab stays as it is.

Example tasks

Recipes for scripts

Daily report from cron

0 7 * * 1-5 cuiar exec --json --workspace shop --permission read-only \
  "Read yesterday's order count and revenue in the store admin" >> ~/reports/sales.jsonl

A wrapper tries again on exit 5 and alerts you on exit 3.

Register a list of people

while IFS=, read name email; do
  cuiar exec --json --workspace events "Register $name ($email) for the 14 November meetup on the event page"
  echo "$name $?" >> register.log
done < attendees.csv

Check a flag before a merge

cuiar exec --json --workspace admin "Is the new-checkout flag on for the EU region in the admin console?"

A Goose or OpenCode session runs it before it merges the change.

Refresh docs screenshots

cuiar --folder ./docs/img --workspace demo \
  "Take screenshots of the settings, billing and team pages of our app. Save them as settings.png, billing.png and team.png."

Move a long job to the cloud

cuiar run --workspace research "Compare the return policies of these 12 shops"
cuiar tasks log <id> -f
cuiar tasks cloud <id>    # before you close the laptop
cuiar tasks back <id>

Cloud hand-off is on Pro and Team and uses 1 credit a minute.

Exit codes

With --json, an error is also JSON on stderr, with its code.

Code	Meaning	What the script does
0	Done.	Use the result.
1	Failed for another reason.	Log it and stop.
2	The command line is not valid.	Fix the call.
3	Not signed in, or the credential cannot do this.	Run cuiar login or set CUIAR_API_KEY.
4	The plan or the credits do not cover this.	Stop and tell a person.
5	The Cuiar app is not open, is busy, or did not answer.	Try again later.
6	Not found.	Check the workspace or the task ID.
7	Too many requests.	Wait, then try again.
8	The task failed or was cancelled.	Read cuiar tasks log <id>.
9	Cuiar cannot be reached.	Try again later.

Agents with a shell

Each of these runs commands and can run cuiar. Most also take an MCP server.

Agent	Run it headless	MCP settings
Goose	goose run -t "..."	~/.config/goose/config.yaml, extensions
OpenCode	opencode run "..." --format json	opencode.json, mcp
Cline CLI	cline "..." --json	~/.cline/data/settings/cline_mcp_settings.json
Amp	amp -x "..."	~/.config/amp/settings.json, amp.mcpServers
Aider	aider --message "..."	None. It runs commands with /run.

Good to know

Permission modes: read-only changes nothing. guard, the default, uses the --folder folders and asks before anything else. full uses any file.
One session per agent: CUIAR_CREDENTIALS_PATH keeps the sessions in another file, for example one file per agent.
JavaScript: cuiar repl runs JavaScript in the app with openTab, inspect, screenshot, download and tabs.

Templates to run from AI Agents CLI

All templates

Each template page shows the run_task or create_routine call to give AI Agents CLI.

Data
Fill in each new row of a sheet
The missing fields from official sources, with a source link for each value.
On an event: When a row is added to the sheet
- Google Sheets
Data
Copy numbers from your dashboards into a sheet
One new row each week with the numbers from each of your dashboards, ready for charts.
On a schedule: Every Monday at 7:00
- Stripe
- Google Analytics
- Any admin panel
- +1 more: Google Sheets
Data
Extract study results into a table
Design, sample size, outcome and effect size with confidence interval from each paper, in one sheet.
You start it: When you start it
- PubMed
- Google Scholar
- Google Sheets
Data
Group open survey answers into themes
Each open answer tagged with themes, with counts, shares, example answers and a short summary.
You start it: When you start it
- Google Forms
- Google Sheets
Data
List every page of a website in a sheet
Each page with its title, description, H1, word count and last update, from the sitemap.
You start it: When you start it
- Any website
- Google Sheets
Monitoring
Watch a page for changes
The exact words that changed. Nothing when nothing changed.
On a schedule: Every hour
- Any website

More agents

All AI agents

Start on the Free plan.

The MCP server, the vault and unlimited routines are free. Steps that your own agent takes use no Cuiar credits.

Get Cuiar Developer docs