Aluy CLI documentation
Everything to install, configure and put the agent to work — from the first command to the autonomous cycle, the full CLI and slash-command reference, the .aluy/ layout and compatibility. Open source under MIT.
Overview
The Aluy CLI is your local agent that works at scale. Instead of suggesting code for you to copy and paste, it acts on your project: it reads and edits files, runs commands and talks to tools — end to end, in your shell.
What runs on your machine stays on your machine: the session, the history, the files, the memory and the provider key (kept in the OS vault). The only thing that crosses the edge is the model call — by default Aluy handles that connection, or you plug in your own provider directly.
It's open source, under the MIT license: what acts on your machine, you can read, audit and change. The mission is simple — to democratize the automation of tasks, processes, tests and development, without depending on a platform team.
The Aluy CLI is the terminal agent — it's not the orchestrator of stories, ADRs and sprints in the Aluy platform. Here the focus is acting on your project.
Installation
Install in one command, as your user, no sudo. The installer resolves the dependencies and puts aluy on the PATH; re-running updates it. The install lives in ~/.aluy.
Linux · macOS
Windows (PowerShell)
Requirements: Linux, macOS or Windows · Node ≥ 20 (the installer ensures it) · ~150 MB free · a connection for the first run.
Full install guide →First steps
On your first aluy, a wizard opens and asks, in this order, for provider, key and model.
- Provider — by default, Aluy handles the model connection and you configure nothing. Or pick a provider directly, with your own credential. Switch later with
/provider. - Key — goes straight to the OS vault (Keychain on macOS, libsecret on Linux, Credential Manager on Windows). Never in plain text, never in the repo.
- Model — pick the tier with
/model; tune the reasoning effort with/effortwhen you need to.
Then send the first task: open the session, describe the goal (or use a /command) and let the agent work. Every action that touches your files asks for permission.
Two flags shape that from the start: aluy --plan runs read-only (it analyzes and proposes, no effect); aluy --yolo lets it run unattended, auto-approving every effect — except the always-ask categories (deletion, network, privilege escalation, package installs), which stay locked, and it refuses to run as root. Full details in the CLI reference.
Want to turn on long-term memory, more context headroom or local models? Run aluy bootstrap — see the Sidecars section.
CLI reference
These are the commands you run from your shell — aluy and its subcommands. Run aluy --help for the built-in list and aluy --version to print the version. The default (no subcommand) opens the interactive session.
Synopsis
The default command
Running aluy with no subcommand launches the interactive TUI session in the current directory. A bare quoted string is taken as the initial goal: aluy "refactor the auth module". The first non-flag token is the goal. On the very first run — before any config exists — the interactive first-run assistant opens automatically before the session, walking through language, backend, provider and model.
Top-level flags
-v, --version info
Prints the version and exits immediately, before mounting the TUI. Format: aluy <cli> (@hiperplano/aluy-cli-core <core>).
-h, --help info
Prints the full built-in help text (every command and flag) and exits.
--yolo session · safety
Full permission on the machine: auto-approves every effect, except the always-ask categories, which stay non-relaxable. Refuses to run as root (uid 0). In a TTY it asks for confirmation once; in headless (-p) it enters directly. The deprecated alias --unsafe still works but prints a warning.
--plan session · safety
Read-only planning mode: the agent analyzes and proposes but produces no effect. If both --plan and --yolo are passed, --plan wins.
Headless / print mode
-p, --print, --exec scripting
One-shot headless run: execute a single goal, print the result, exit. The prompt can be inline (-p "goal") or piped on stdin (echo "goal" | aluy -p). --print and --exec are aliases.
--output-format text|json|stream-json scripting
Only valid with -p. text (default) prints just the result; json prints a single-line object; stream-json emits a NDJSON stream of live events.
--quiet scripting
Only with -p: suppresses the progress ticks and stderr noise, leaving just the result. Ideal for pipes and CI.
--cycle, --cycles <N>, --cycle-for <dur> scripting
Only with -p: runs the goal autonomously in cycles (the headless form of /cycle). It requires a ceiling — --cycles <N> (max iterations) or --cycle-for <dur> (wall-clock, e.g. 30m, 2h). Anti-runaway: both are clamped to hard limits.
Model and backend
--tier <tier> model
Picks the model tier for the session (changeable at runtime with /model). Passing the literal custom without --model is a usage error.
--model <slug> · --provider <name> model
--model selects a curated model slug from the catalog and forces tier: custom. --provider must be paired with --model. Both are data, never a credential — the broker resolves slug/provider to a credential server-side.
--effort <value> model
Reasoning-effort passthrough (any non-empty value ≤ 32 chars, e.g. low/medium/high). No tier gate; the broker/provider validates the value.
--backend broker|local backend
Chooses how the model is reached. broker (default) routes the call through the Aluy broker. local talks to your provider directly with your own (BYO) credential from the OS vault.
--local-provider · --local-model · --local-auth · --local-base-url backend · local
Only under --backend local. --local-provider is anthropic|openrouter|openai; --local-model is the provider-native slug; --local-auth is apikey|oauth; --local-base-url is the endpoint (anti-SSRF guarded). Each falls back to env (ALUY_LOCAL_*) or config when omitted.
Limits and safety
--max-tokens <N> · --max-iterations <N> · --max-output-tokens <N> budget
--max-tokens is the session token budget (default 1000000); --max-iterations caps the model→tool→observation loop (default 300); --max-output-tokens caps output per call. On hitting a ceiling the run pauses and asks whether to continue or stop. Each is clamped.
--budget / --no-budget budget
Toggles the session budget circuit-breaker. Default off on --backend local (BYO, unlimited by design), always on with the broker.
--self-check / --no-self-check quality
Forces the self-check loop on or off (re-anchor the objective and verify before declaring "done"). With no flag it is auto: weaker tiers turn it on.
--autocompact-at <ratio|%|off> context
Window-occupancy threshold that triggers auto-compaction (default 0.85). Accepts 0..1, a percentage (85%), or off. The sugar --no-autocompact equals --autocompact-at off.
--no-subagents agents
Disables local parallel sub-agents (the spawn_agent tool). By default sub-agents run in parallel at depth ≤ 1, inheriting permissions and a shared ceiling.
Session, resume & display
--continue · --resume [<id>] · --new session
--continue resumes the last session of this directory. --resume with no id lists saved sessions; with an id it resumes that one. --new starts fresh.
--lang pt-BR|en ui
TUI language. Precedence: flag > config > locale auto-detect > default pt-BR. It does not translate the agent's output. Toggle at runtime with /lang.
--split · --fullscreen ui
--split starts in Advanced View (CHAT | LOG side by side; Ctrl+L toggles). --fullscreen starts in Cockpit mode (alt-screen). Both persist to config.
--dense · --ascii ui
--dense compacts the TUI. --ascii uses a safe glyph profile to avoid Unicode "tofu" (same as ALUY_SAFE_GLYPHS=1).
Subcommands
aluy bootstrap [--agent] setup · sidecars
Provisions the local sidecars (mem0, headroom, ollama) in user space — it offers each one and you choose. --agent lets Aluy install them through its own agent on systems with no pinned artifact. There is no aluy onboard subcommand: the interactive first-run assistant (language, backend, provider, model) opens automatically the first time you run aluy.
aluy login [--token <PAT>] [--org <id>] [--device] [--provider <p>] [--oauth] account
Authenticates. By default it runs the broker device-flow. --token passes a Personal Access Token directly (CI); --org selects an organization; --provider logs in to a local backend (BYO), and with --oauth does an OAuth-PKCE sign-in.
aluy logout · aluy whoami account
logout revokes the session and erases the keychain credential. whoami shows the current user, org and scopes — never the secret.
aluy doctor [--deep|--test] [--json] health
Validates the install: credential, broker, MCP servers, agent profiles, config, version and memory. --deep adds a live tier test (costs one model call). --json prints a machine-readable array; exit code is non-zero if any check fails.
aluy agents · skills · workflows · models · providers discovery
Read-only listings, exit 0, no model call. They show the mapped .md agent profiles, the SKILL.md skills, the workflow definitions, and the available providers/models (broker catalog + local BYO).
aluy mcp <search|add|list|remove> tools
Manages MCP connectors from the shell (the same engine as the in-session /mcp). add <name> -- <cmd> adds a local stdio server; --project writes to the project .mcp.json.
aluy cron <add|list|edit|enable|disable|rm|run> scheduling
Schedules persistent headless tasks via the OS scheduler (no daemon). Live on Linux (crontab); Windows/macOS to come. Each run executes as aluy -p "<task>" through the permission lock. add <when> "task" takes a 5-field cron (e.g. "0 9 * * 1-5"); list shows id, on/off, schedule, task and yolo; edit / rm / run <id> reconfigure, remove or run now; enable / disable <id> toggle without deleting.
Environment variables
Several flags read a matching env var as fallback: ALUY_TOKEN, ALUY_ORG, ALUY_BACKEND, ALUY_LOCAL_*, ALUY_MAX_TOKENS, ALUY_BUDGET, ALUY_AUTOCOMPACT_AT, ALUY_SAFE_GLYPHS. NO_COLOR disables colored output.
Exit codes: 0 success · 1 error · 2 usage error — it exits without mounting a session.
Slash commands
Inside a running session, type / at the start of the line to open the menu — filter as you type, then Tab/Enter completes. These are commands you give, not tools the agent invokes. A compact, grouped overview is on the Commands page.
Account & session
/login · /logout · /whoami · /doctor account · read-only
Sign in/out and inspect the session. /whoami shows user, org, scopes and a redacted token hint — never the secret. /doctor is the read-only health check (credential, broker, catalog, MCP, profiles, config, version, memory) — each ✓/⚠/✗ with a fix hint. Both run in parallel mid-turn.
/help · /usage · /rename · /history session
/help lists every native command; /usage shows tokens, window occupancy and tier. /rename gives the session a label + color (also sets the terminal window title). /history browses and resumes an earlier session without leaving Aluy.
/compact · /clear [full|memory] · /ask · /notify session · context
/compact summarizes the conversation to shrink the window. /clear clears context; memory/full also wipe memory (confirm). /ask is a parallel read-only question. /notify toggles the attention bell.
Workspace, project & config
/undo · /redo · /rewind workspace
Step the agent's last file edit backward/forward from the per-session journal. /rewind (Esc Esc) goes back to an earlier checkpoint — code and/or conversation.
/permissions · /tools · /add-dir workspace
/permissions shows the rules (read=allow, write/bash=ask, always-ask=locked). /tools is the unified read-only inventory (native, MCP per server, delegation tools, permission state). /add-dir authorizes an extra directory for the session.
/init · /memory · /todo project
/init analyzes the repo and writes AGENT.md (you confirm the diff). /memory <list|forget|edit|pin|unpin> curates the agent's memory (global + project; a pinned fact stays data, never an instruction). /todo manages the persistent backlog.
/model · /provider · /effort · /theme · /lang · /split · /fullscreen config · ui
/model switches the tier (shows tier only, never the credential); /provider sets the provider name for Custom mode; /effort sets the reasoning effort. /theme aluy-dark|aluy-light|aluy-slate and /lang (pt-BR/en) persist the choice. /split and /fullscreen toggle the LOG panel and Cockpit mode.
Autonomy & multi-agent
/cycle <interval|--por dur|--auto> "task" autonomy
Runs a task in cycles until done, with hard ceilings and an automatic stop (anti-runaway), through the same permission gate. Two rhythms: fixed (5m or --por <dur>) or --auto. In-flight: pause, resume, edit, status, stop.
/cron · /subagent · /back · /rooms scheduling · multi-agent
/cron is the in-session form of aluy cron. /subagent <name> opens a 1:1 focus with a profile; /back returns. /rooms <list|new|read|watch> creates and follows agent-to-agent rooms live.
/agents · /skills · /workflows · /mcp discovery · tools
Read-only listings of what the session mapped at boot. /workflows run <name> runs one in sequence; use activates flow mode. /mcp <search|add|list|remove|disable|enable|reconnect|reload> manages connectors without leaving the session.
Inside the session, type /help for the live list, or Ctrl+P for the command palette. The aliases /view → /split and /cockpit → /fullscreen resolve automatically.
.aluy/ structure
Aluy keeps two homes: a global one under ~/.aluy/ (install, config, sidecars, cross-project memory) and a project one — the instruction file at the repo root plus an optional .aluy/ folder. Everything under ~/.aluy/ is the confined client kernel: the agent's own path-deny rules forbid it from reading, editing or running anything in there.
Project: the instruction file
The native project instruction file is AGENT.md at the repo root — what /init creates. Aluy reads three filenames as project instructions, in this precedence, composing all that are present:
Precedence is AGENT.md › AGENTS.md › CLAUDE.md. They are read once at startup and injected into the system prompt, each under a header marking its source. Symlinks that escape the project root are rejected and nothing is read.
Project: the .aluy/ folder
Global: ~/.aluy/
The three sidecar directories appear only after you run aluy bootstrap and choose to provision them. Without the sidecars Aluy still works — it just loses long-term memory, extra context headroom and local models.
/cycle — run until done
With /cycle, you describe the task and the agent works in cycles on its own until it's done — no babysitting. It's the "kick it off and go do something else".
It comes with a handbrake: hard ceilings on time and steps, and an automatic stop if something goes off the rails. The anti-runaway — no robot escaping control.
- Good for: fixing tests, mass sweeps, repetitive migrations, long tasks with a clear "done" criterion.
- Every effect that touches your files still passes through the permission lock.
Subagents
Each subagent is a profile (.md file) with its own focus. You ask for the specialist and the agent itself creates the subagent for you — describe what you need ("a security reviewer", "an E2E QA") and it generates the profile with the role, tone and limits. You don't write the .md by hand (but you can edit or create one if you want).
They work in parallel, without mixing contexts: each subagent has its own dedicated sub-session. A fleet, not a lone agent.
Rooms
Rooms (/rooms) put multiple agents talking to each other about the same problem — debating, splitting and combining the work. You follow the conversation in real time and step in when it makes sense.
MCP — connect tools
Through MCP (the open connector standard), the agent talks to external tools and integrations — databases, APIs, services. It's what gives the agent real access to what you already use, not just conversation.
Compatibility — Codex & Claude Code
Already using Codex or Claude Code? Aluy understands your structure. No reconfig. Point Aluy at your project and it reads the same instruction and configuration files you already keep.
Project instruction files
AGENT.md— the Aluy native file (what/initwrites), also the generic agent convention.AGENTS.md— the same file Codex (OpenAI) uses.CLAUDE.md— the same file Claude Code uses.
Precedence is AGENT.md › AGENTS.md › CLAUDE.md — all that are present compose together.
Structure parity
.mdagents accept the Claude Code tool names — mapped to the native ones.- Hooks in the Claude Code
settings.jsonformat, and user commands in.md. /rewind+ checkpoints, with parity to Claude Code.
Sidecars
Sidecars are optional local boosters that run on your machine (listening on 127.0.0.1 only) to give the agent long-term memory, more context headroom and local models. Aluy works without them — it just loses those features. Nothing breaks. Turn them on with aluy bootstrap.
Architecture
Under the hood, the Aluy CLI is a single process in your terminal — a monolithic delivery, no hidden server. The interface (the TUI) talks to the core, the engine that reads and edits files, runs commands and decides the next steps. Between the agent and your project sits the permission lock: the single point every effect passes through before it happens.
The state lives on your machine: the session memory (and the long-term one via mem0), your key in the OS vault, your files and your shell. Sidecars are optional local boosters that listen on 127.0.0.1 only.
- The only things that cross the edge are the model call and the MCP connectors you turn on.
- Session, history, files, memory and your key never leave your computer.
The permission lock is a single point: no file is changed and no command runs without passing through it. It's what keeps you in control.
Memory
The agent remembers project decisions and context from one conversation to the next — global and per-project facts. You control all of it with /memory: see what it stored, pin what matters and forget what's no longer useful.
- Long-term memory depends on the mem0 sidecar; without it, only the current session's memory applies.
/clear memorywipes everything the agent stored (asks for confirmation).
Themes
The session comes in three themes — light, dark and slate — so you can set it to whatever you like looking at all day. Switch with /theme aluy-dark | aluy-light | aluy-slate; your choice is saved.
aluy-light — light stone background, amber accent.aluy-dark — near-black, high contrast.aluy-slate — deep stone with teal hairlines.The themes come from the Aluy Design System tokens: color, typography and density come from variables, never from raw style.
Doctor
/doctor is the read-only diagnostic of your install: it checks model, key, connection, MCP and config — and points to a fix hint when something is out of place. It changes nothing, only reads.
FAQ
Does my data go to the cloud?
No. The session, the history, the project files and the memory stay on your machine. The only thing that crosses the edge is the model call.
Where does my key live?
In the OS vault (Keychain, libsecret, Credential Manager) — never in plain text, never in the repo. Aluy shows the model tier, never the credential.
How does Aluy talk to the model?
By default, Aluy handles the model connection — you configure nothing. If you prefer, plug in your own provider directly, with your own credential (API key or OAuth): it's your usage, under your control.
Is there a cost?
The Aluy CLI is open source, under MIT. In direct mode, model usage runs through your own account at the provider. The sidecars run locally, with no API cost.
Is it safe to leave /cycle running on its own?
/cycle has hard ceilings on time and steps, and an automatic stop. And every action that touches your files passes through a permission lock.
Can I read and modify the code?
Yes — it's open source under MIT. Read it, audit it, open issues and fork it. What acts on your machine, you deserve to be able to inspect. Aluy is in beta; expect rough edges and fast iteration.
Didn't find the answer? Start with the Install page or run /doctor inside the session.