Every command, in one place.
Two surfaces, in the order you meet them. In your shell you call aluy with subcommands and flags. Once a session is open, slash commands are what you type inside it. This page is the complete list of both, grouped by what you are trying to do. If you are still learning what to reach for, start with the guide.
The aluy command line
Open a session
— the default, with no subcommand.Opens the interactive session in the current directory. A quoted string is taken as the starting goal. The first run opens the setup assistant first.
Resumes the last session of this directory.
With no id, lists the saved sessions to pick from. With an id, resumes that one.
Starts a fresh session, ignoring the saved ones.
Opens the session with the Telegram bridge on, so the agent can reach you off the terminal.
Decide how much it may do
— the setting that matters most.Read-only planning: the agent analyzes and proposes, and produces no effect. If you pass both, this one wins over --yolo.
Auto-approves every effect, except the always-ask categories, which cannot be relaxed. Refuses to run as root. In a terminal it confirms once; in headless mode it enters directly.
Turns off parallel subagents. By default they run at depth 1 or less, inheriting the parent’s permissions and sharing one ceiling.
Run it without a session
— scripts, pipes and CI. All of these need-p.--exec "<goal>"
Runs one goal, prints the result and exits. The goal can be inline or piped on stdin.
How the result comes back: just the text, a single JSON object, or a live stream of events, one JSON object per line.
Suppresses the progress ticks and the stderr noise, leaving only the result.
--cycle-for <dur>
Runs the goal autonomously in cycles — the headless form of /cycle. A ceiling is required: iterations with the first, wall-clock time with the second.
- durations
- 30m
- 2h
Choose the model
— which one answers, and how it is reached.Picks the model tier for the session. Changeable at runtime with /model.
Selects a curated model from the catalog and forces the custom tier. The two must be passed together.
Reasoning-effort passthrough: any non-empty value up to 32 characters. No tier gate; your provider validates it.
- typical
- low
- medium
- high
Local calls your provider directly with your own credential; nothing is routed through or counted by Aluy. Broker routes through a central backend, which is not available today.
Which provider the local backend talks to.
- values
- anthropic
- openrouter
- openai
The model slug, exactly as that provider names it.
A stored API key, or a subscription OAuth sign-in.
The endpoint to call, for an OpenAI-compatible provider or a local runtime. Aluy refuses addresses that would make it call back into your own private network.
Set the ceilings
— so a run cannot go all night on your budget.The session token budget.
Caps the model → tool → observation loop.
Caps the output of a single model call. On reaching any of these three ceilings, the run pauses and asks whether to continue or stop.
--no-budget
Toggles the session budget circuit-breaker.
--no-self-check
Forces the self-check loop on or off: re-anchor the objective and verify before declaring the work done.
How full the model’s window may get before Aluy compacts the conversation.
- accepts
- 0.85
- 85%
- off
Change how it looks
— all of these persist to config.Interface language. It does not translate the agent’s output. /lang toggles it at runtime.
Starts in Advanced View, with CHAT and LOG side by side. Ctrl+L toggles it.
Starts in Cockpit mode, which takes over the whole terminal and restores what was there when you leave.
Compacts the interface — less padding, more content per screen.
Switches to a safe symbol set, for fonts that show empty boxes instead of symbols.
Set up the install
— subcommands: they do one job and exit.Guided setup: language, backend, provider, key, model, the MCP servers it offers, and the sidecar profile. Step 2 right after the install, and you can run it again to switch.
Installs the optional local programs — memory, context compression and local models — under your own user account. It offers each one and you choose. By default it installs them through its own agent; --no-agent takes the direct, deterministic path with no model involved.
- sidecars
- mem0
- headroom
- ollama
Prints what is actually in effect — profile, toggles, and where each setting came from.
Authenticates. With a provider, it stores that provider’s API key in your vault; with OAuth, it signs you in with a subscription instead. With neither, it runs the device flow of the central backend.
- options
- --provider <p>
- --oauth
- --token <token>
- --org <id>
- --device
aluy whoami
The first revokes the session and erases the stored credential. The second shows user, org and scopes — never the secret.
Check and inspect
— read-only; no model call, exit 0.Validates the install: credential, provider reachability, MCP servers, agent profiles, config, version and memory.
Read-only listings of what Aluy mapped: agent profiles, skills, workflow definitions, and the providers and models available to you.
- and also
- skills
- workflows
- models
- providers
--version
Prints the version and exits before the interface mounts.
--help
Prints the full built-in help — every command and flag — and exits.
Leave work running
— scheduled tasks and services.Schedules persistent headless tasks through the OS scheduler, with no daemon. Each run executes headlessly, through the permission gate.
- subcommands
- add
- list
- edit
- enable
- disable
- rm
- run
Agents with a routine. Starting one shows you the manifest and asks first; attaching puts you inside a running service to watch and steer it, and Ctrl+C detaches without stopping it.
- subcommands
- list
- status
- create
- install
- uninstall
- start
- stop
- logs
- attach
Connect external tools
— the same engines as the in-session commands.Manages MCP connectors from the shell. Adding one takes a name and the command that starts the server.
- subcommands
- search
- add
- list
- remove
Connects the bot that reaches you off the terminal. Signing in stores the @BotFather token in your vault, and the allowlist starts closed.
- subcommands
- login
- logout
- allow
- deny
- status
Access and backend
— who you are, and where the model call goes.Personal Access Token, for signing in without a prompt.
Which organization to act under.
Whether the call goes straight to your provider (local) or through the central backend (broker).
Which provider the local backend talks to.
The model slug, exactly as that provider names it.
Whether the local backend uses a stored API key or an OAuth sign-in.
The endpoint to call, for an OpenAI-compatible provider or a local runtime.
The provider key itself, for machines where the OS vault is not available.
The bot token, instead of storing it with aluy telegram login.
Where the central backend lives. You only set this if you run your own.
Where the identity service lives. Same caveat.
Overrides the OAuth client ids and the redirect URI used when signing in with a subscription.
Limits and ceilings
— the same ceilings the flags set, for when there is no command line to put a flag on.The session token budget. Default 1000000.
How many times the model may go round the tool loop. Default 300.
The cap on a single model reply.
Turns the budget circuit-breaker on or off.
How full the model’s window may get before Aluy compacts the conversation. Default 0.85.
The ceiling on how many times one session may auto-compact.
Overrides the context window Aluy discovered for the model, when that number is wrong.
Forces the verify-before-done loop on or off.
How often that verification runs.
How many verifications one run may spend.
How many facts one session may write to memory.
The subagent ceilings: how many per call, how many at once (default 4), and how long one may sit idle (default 5 minutes).
How long to wait for an MCP tool call. Default 60000.
How long to wait for an MCP server to come up. Default 20000.
The cap on one streamed reply. Default 24 MB.
Removes that cap.
How much text a fetched page may contribute.
The memory ceiling for the Aluy process itself. Default 4096.
How close to that ceiling Aluy starts shedding load. Default 0.8.
Stops it watching its own memory use.
How many times to retry a failed model call. off disables retrying; it is on by default.
How long to wait between those retries.
Anti-runaway guards
— they stop a run that is busy but going nowhere. All are on by default.The repeated-output guard, which aborts a reply that keeps saying the same thing: how many identical lines in a row are allowed (default 25), how long a repeating cycle may run (default 2000 characters), and a switch to turn the guard off.
The stuck watchdog, which pauses and asks you for direction instead of spinning: the same tool called four times, the same error three times, three empty turns, six iterations without progress — and a switch to turn it off.
What happens when the model says it will use a tool and then does not: how many times Aluy may nudge it to carry on (default 4), when the nudge gets firm, when to give up, and a switch to turn it off.
The kill switch for the supervisor — the layer that watches the run and, when the sidecars are up, uses them to steer it. It never touches the permission gate.
The same thing, turned off explicitly with 0 or false rather than by the kill switch.
Whether that supervisor may use the memory sidecar.
Whether it may use the local judge.
Turns off the judge that decides when a /cycle has finished.
Terminal and output
— for terminals that render badly, and for machines reading the output.The interface language. It does not translate the agent’s output.
The safe glyph profile, for fonts that show empty boxes instead of symbols.
Forces plain ASCII outright, when the safe profile is still not enough.
Turns on the richer glyph set, for terminals with a Nerd Font installed.
Forces the status marks to ASCII.
Forces them back to Unicode.
Compact or comfortable spacing.
Starts in Cockpit mode.
No spinners and no blinking — the reduced-motion setting.
The bell that calls you when the agent needs attention. /notify toggles it live.
The inline suggestions in the composer.
Whether the model name stays visible in the interface.
Hides the cycle panel.
How long the splash screen stays up.
Where the composer anchors on screen.
Sends each screen update in one piece, so the interface does not flicker while it redraws.
Whether Aluy may set the terminal background to match its theme.
How long to wait while asking the terminal what its background color is.
More detail in headless runs.
Not an Aluy variable, but honored: it turns color off everywhere.
Sidecars and memory
— where each sidecar listens, and whether the agent recalls anything.The memory sidecar: its host, port or full URL, the virtualenv it runs from, and which embedder it uses.
The context sidecar: its host, port or full URL, the binary to launch, and a switch to turn it off.
The local model runtime: its host, port or full URL, and the directory it keeps models in.
Stops the agent recalling long-term memory at all. Recall is on by default.
How relevant a remembered fact must be before it is brought back.
Where agent-to-agent rooms are stored.
Sandbox, updates and debugging
— escape hatches. You should not need these day to day.Runs shell commands inside the sandbox.
Runs MCP servers inside the sandbox.
Turns the sandbox off. The name is the warning.
The environment name, which decides how strictly a sandbox failure is treated.
Turns off the built-in tools, leaving only what MCP provides.
Silences the warning about running unattended on a weaker model.
Whether Aluy updates itself quietly in the background.
How often it checks.
Stops it checking at all. Aluy also skips the check on CI.
How long an upgrade may take before it is abandoned.
Verbose internal logging.
Logs what the interface is drawing.
Redraws in place instead of appending, for diagnosing flicker.
A flag always beats the variable, and the variable always beats what is saved in your config. aluy config prints which of the three won for each setting. A few more variables exist that Aluy sets for itself — those are not meant for you to set.
Exit codes: 0 success · 1 error · 2 usage error — on a usage error it exits without mounting a session.
Slash commands
Put the agent to work
— start something that finishes without you.Runs a task in autonomous cycles until it is done, with hard ceilings and an automatic stop.
- rhythm
- 5m
- --por <dur>
- --auto
- in flight
- pause
- resume
- edit
- status
- stop
Schedules a task to run on its own, on your machine, whether or not a session is open.
- subcommands
- add
- list
- edit
- enable
- disable
- rm
- run
Agents with a routine: they wake on schedule, work inside a budget and report on your channel.
- subcommands
- create
- list
- status
- install
- uninstall
- start
- stop
- logs
- attach
Manages the session’s persistent backlog of tasks.
Work with more than one agent
— your fleet, and the rooms they talk in.Opens a focused 1:1 sub-session with one profile. Each subagent keeps its own context, so a long task does not crowd out yours.
Leaves the subagent focus and returns to the main session.
Creates and follows rooms where several agents talk to each other about the same problem, live.
Lists the mapped agent profiles, global and project, valid and rejected with the reason.
Connect it to what you use
— external tools and the phone.Manages MCP connectors without leaving the session: search the open registry, add a local server, list what is mapped.
- also
- disable
- enable
- reconnect
- reload
The agent on your phone: it reports when work ends, asks when it needs a decision, and warns when it pauses. Only the chats you allow.
- subcommands
- login
- logout
- allow
- deny
- status
The unified inventory of the agent’s tools — native, MCP per server, and the permission state of each. Read-only.
Lists the mapped SKILL.md skills, global and project, valid and rejected.
A numbered list of steps the agent runs in order, each one optionally handed to a subagent. On its own, it lists the ones it found.
- subcommands
- run <name>
- use
Undo, and keep the context clean
— when it went wrong, or the session got long./redo
Steps the agent’s last file edit backward or forward, from the per-session journal.
Goes back to an earlier checkpoint — the code, the conversation, or both. Esc Esc opens it.
Summarizes the conversation to free room in the model’s window, without losing the thread.
Clears the session context.
- also wipes memory
- memory
- full
Tokens used, how full the model’s window is, and the current tier.
Browses earlier sessions and resumes one without leaving Aluy.
A parallel, read-only question that does not interrupt the work in progress.
Set it up
— project, model, permissions and looks.Reads the repository and writes the project’s ALUY.md. You see the diff and confirm it.
See, edit, pin or forget what the agent remembers — global and per project. A pinned fact is kept for good, and is given to the model as information, never as an order.
/provider
/effort
Switches the model tier, sets the provider name in direct mode, and tunes the reasoning effort. Shows the tier, never the credential.
What the agent may do without asking: mode, grants and safe tools. The categories that always ask cannot be unlocked here.
Authorizes one extra directory for this session, outside the project root.
/lang pt-BR|en
Switches theme and interface language. Both auto-detect on boot and persist.
- values
- aluy-dark
- aluy-light
- aluy-slate
- pt-BR
- en
/fullscreen
Toggles the side-by-side LOG panel and Cockpit mode. Both persist to config.
- aliases
- /view → /split
- /cockpit → /fullscreen
/logout
/whoami
Signs in and out, and shows the current account, org and scopes — never the secret.
When something is off
— read-only; it changes nothing.Checks the install end to end — credential, provider, catalog, MCP, profiles, config, version and memory — and prints a fix hint next to whatever failed.
- also
- fix
Lists every native command, live, inside the session.
Gives the session a label and a color. It also sets the terminal window title.
Toggles the bell that calls you when the agent needs attention.