Agents, skills and the CLI¶

Why the alis command line is built for coding agents as much as for people, how the CLI, the Alis Build MCP server and the editor plugins divide the work, what skills are and why they are loaded live, and where the safety model insists on a human. For builders deciding how much of their platform work to hand to an agent.

One binary, two faces¶

alis behaves differently depending on how it is called. With no arguments it opens the TUI, a full-screen interface for a person at a terminal. With a command it is a CLI that prints one result and exits. The split is strict: the TUI refuses to start when stdin or stdout is not a terminal, and instead prints a JSON envelope (TTY_REQUIRED) pointing at the headless commands. An agent that types alis by mistake gets a machine-readable correction rather than a screen nobody can see.

This matters because the two audiences want opposite things. A person wants to explore, see progress, and be asked before something risky happens. An agent wants determinism: the same command, the same shape of answer, and a clear signal when it must stop.

What "made for agents" means in practice¶

Four design choices carry most of the weight.

Exactly one JSON object on stdout. Under --json, stdout holds one document: the result, the final operation, or an error envelope. Progress goes to stderr as NDJSON, one small event per line, and there is no final stderr event: stdout arriving is the completion signal. Results are pruned to what is actionable, so a successful build is under a kilobyte and an absent field means zero. An agent can read stdout whole and never needs tail or grep, which would silently drop the fields it is looking for.

Context comes from the working directory. Inside ~/alis.build/<org>/build/<product>/<service>/, the CLI knows the build environment, product and service. alis build with no argument builds the service you are in; alis context view --json shows the resolution and the product's deployment environment ids. The --cwd flag gives the same resolution to tools that cannot change directory. The effect is that an agent rarely has to construct identifiers, and never has to guess deployment environment ids.

Long work is a handle, not a wait. --async returns an operation name at once, and alis operations wait <name> re-attaches and blocks efficiently until it completes. Interrupts never cancel the server-side operation. An agent that loses its connection, or a script that has to hand over to another process, resumes from the name.

The manual ships in the binary. alis docs prints the operating manual, topic by topic: output contract, exit codes, safety, context, recipes. alis <cmd> --help is the source of truth for flags. A skill for a task can be found and loaded from the command line too. An agent does not need to be pre-loaded with platform knowledge; it reads what it needs when it needs it.

Three planes¶

flowchart TB
    A[Coding agent] -->|shell| CLI["alis CLI<br/><small>local execution plane</small>"]
    A -->|no shell| MCP["Alis Build MCP server<br/><small>mcp.alis.build, control plane</small>"]
    P["Editor or agent plugin<br/><small>session glue</small>"] -.->|primers, session ids,<br/>approval prompts| A
    CLI --> Platform[(AlisX)]
    MCP --> Platform

The CLI is the local execution plane. Anything that runs where a shell exists goes through it: define, build and deploy, package installs, context detection, skills discovery and loading. It is deterministic and chains steps into one call (alis build --deploy, alis define --install).

The MCP server at mcp.alis.build is the control plane. It offers SpecIt, and a headless fallback: server-side RunDefine, RunBuild and RunDeploy, plus SearchSkills and LoadSkill for agents that have no shell at all.

Editor and agent plugins are session glue. They inject primers and session ids and make approvals ergonomic. They never replace the CLI or the MCP server.

The rule the manual gives is short: with a shell, use alis; without one, use the MCP server, whose skills tools also step in when alis skills reports that the backend is outdated.

Skills: instructions, loaded live¶

The Skill Store is the platform's knowledge and know-how. A skill is an instruction document that teaches how to do one thing well, with optional reference files. The agent workflow is search, load, resource: alis skills search ranks the catalog by meaning, alis skills load prints the chosen document, alis skills resource fetches a file it references.

Skills load live from the Skill Store rather than being installed up front, because every installed skill costs an agent context before its first prompt; loading live keeps that cost at one entry however large the catalog grows. How skills work explains this, the loop from capture to feedback, where skills come from and the safety scan.

The safety model¶

Automation has to stop somewhere, and the CLI makes the stopping points explicit rather than leaving them to the agent's judgement.

Automation tiers classify commands by risk. Mutating commands (define, build, deploy, package installs, setting variables) and destructive ones (deleting a block, unpublishing a skill, unsetting variables, revealing secret values, uploading diagnostics) can each be gated. The manual tier gates both; the default balanced tier gates destructive only; autonomous gates neither. When a gate applies, a person at a terminal sees a [y/N] prompt; a headless caller gets exit code 3 and an APPROVAL_REQUIRED envelope whose retry is the same command with --approve. The contract for agents is that they never add --approve themselves: they show the human what changes and run the retry after a yes.

The production gate is separate and applies at every tier. Deploying to a production environment, or changing or revealing its variables, exits 3 with PRODUCTION_CONFIRMATION_REQUIRED. Only --confirm-production lifts it; --approve and --yes never do. Approval applies to that one deployment. --plan-only is not gated, because a Terraform plan changes nothing, which makes it the right first step before asking.

Session modes are not consent. An agent running in an "auto" or "accept edits" mode has not been given permission to deploy to production. The plugin asks for native confirmation of the exact invocation, and that confirmation is what counts.

The result is a division of labour that holds up under automation: the agent does the deterministic work, the CLI tells it exactly when to stop, and a person makes the decisions that spend money or touch production.

Where the human stays¶

Some steps are deliberately left to people. Signing in is a browser flow with a code to paste. Choosing the active account, which every tool's usage is measured against, is a decision the CLI refuses to make for you. Support conversations go to a Specialist, a working Builder who reads them first, even when an agent wrote them, which is why the manual asks for short, factual messages with the evidence attached separately. And when an agent hits exit code 3, the next word is yours.