Work with a coding agent¶
In this tutorial you set up a coding agent to drive AlisX for you through the alis CLI: install the CLI, hand the agent its manual, let it find and load the skill for the job, and run one define, build and deploy loop with the agent watching the operation. At the end you have an agent that speaks the CLI's JSON contract and knows where it must stop and ask you. It is for builders who already use an agent such as Claude Code, Codex, Gemini CLI or OpenCode.
The steps use Claude Code as the example. The commands the agent runs are the same for any agent with a shell.
1. Install the CLI¶
Follow Install the CLI through the sign-in step, or let the agent do it. The agent's loop for a fresh machine is documented in alis docs setup: install, then call alis setup status --json and act on .next until .ready is true.
2. Install the agent's Alis Build plugin¶
The steps list includes your agent's Alis Build plugin, for example "name": "Claude Code (Alis Build plugin)", with installed: false and the command that installs it. Install every missing step in one go:
Steps that need you (for example a package manager's password prompt) come back under needs_user; run those yourself. If your agent is not recorded on your build profile yet, tell the CLI:
Restart the agent so it sees the new PATH and plugin.
3. Hand the agent its manual¶
Open your agent in a service folder under ~/alis.build/<org>/build/<product>/ and give it this first prompt:
Run `alis docs` and read it in full. From now on, operate the Alis platform
only through `alis` commands with --json, one standalone command at a time.
The manual tells the agent the rules it must follow: one JSON object on stdout, progress on stderr, --async for long operations, exit code 3 means stop and ask a human. Everything below is what the agent does with that knowledge.
The agent can read this documentation too: https://docs.alisx.com/llms.txt indexes every page as markdown (see Documentation for agents).
4. Let the agent see where it is¶
{
"organisation": "acme",
"product": "shop",
"packageId": "acme.shop.orders.v1",
"serviceFolder": "/home/me/alis.build/acme/build/shop/orders/v1",
"defineFolder": "/home/me/alis.build/acme/define/acme/shop/orders/v1",
"environments": [
{"id": "<dev-env-id>", "displayName": "Development", "production": false, "status": "ACTIVE", "projectId": "<project-id>"},
{"id": "<prod-env-id>", "displayName": "Production", "production": true, "status": "ACTIVE", "projectId": "<project-id>"}
]
}
Because the working directory is inside the service folder, the agent can omit the package ID on every command. When its tool cannot change directory, it uses alis --cwd /absolute/path <command> instead. Deployment environment ids come from here, never from guessing.
5. Let the agent find the skill for the job¶
Ask the agent to add a field to the service's API. Before it edits anything, it searches the skills catalog:
{
"queriedSkills": [
{"id": "dbd-add-protos", "displayName": "Initialise Definitions", "description": "Use this skill when …", "version": "1", "source": "USER", "vetVerdict": "PASSED"}
]
}
It loads the best match and follows it:
Skills are loaded live, one at a time, so the agent's context holds only the instructions it needs. If a skill references a file, alis skills resource <id> <path> fetches it.
6. Define¶
The agent edits the .proto in the define folder, then checks it compiles before committing:
{"valid": true, "diagnostics": [], "git": {"uncommittedFiles": ["orders.proto"], "unpushedCommits": 0}}
It commits and pushes, then publishes the contract and installs the generated packages:
{"schemaVersion": 1, "name": "operations/<id>", "done": true, "status": "succeeded", "version": "1.5.0"}
7. Build and deploy, asynchronously¶
The agent implements the change, commits and pushes, then starts a build with a deploy attached and returns at once:
{"schemaVersion": 1, "name": "operations/<id>", "done": false, "status": "running", "next": "alis operations wait operations/<id> --json"}
It runs the next command to wait, which blocks efficiently and streams progress on stderr:
{"elapsed":"0:04","operation":"operations/<id>","progress":"Building image neurons/orders-v1"}
{"elapsed":"2:31","operation":"operations/<id>","progress":"Deploying to Development"}
{
"schemaVersion": 1,
"name": "operations/<id>",
"done": true,
"status": "succeeded",
"version": "1.5.0",
"images": [{"path": "."}],
"deployments": [{"name": "…/deployments/orders-v1", "state": "RUNNING", "logsUri": "https://…"}]
}
The agent reads stdout whole: the final JSON is the result, even when the operation fails (then it carries error, and alis logs build|deploy operations/<id> --json has the log). It never sleeps in a loop or pipes the output through tail.
8. Hit the production gate¶
Ask the agent to promote the version to production. It previews first, which is not gated:
Then it tries the deploy:
{
"error": {
"code": "PRODUCTION_CONFIRMATION_REQUIRED",
"message": "…",
"retry": "alis deploy --version 1.5.0 --json -e <prod-env-id> --confirm-production",
"agent": "…"
}
}
Exit code 3. This is the moment the agent must stop. It shows you the version, the deployment environment and the retry command, and asks. Only after you say yes does it run the exact retry. An agent never adds --confirm-production on its own; --approve and --yes never lift this gate; and approval covers that one deployment only.
9. Save the session¶
When the work is done, the agent can save its transcript to your Alis history so that alis ask can see it later:
The command asks you to confirm before anything leaves the machine. Credentials are masked first.
What you have¶
- An agent with the Alis Build plugin installed and the CLI manual read.
- An agent that resolves context from its working directory, loads skills live, and parses one JSON object per command.
- A define, build and deploy loop run with
--asyncandalis operations wait. - A production gate the agent respects: exit code 3, ask the human, run the exact retry.
Agents without a shell¶
An agent that cannot run commands, for example one hosted in a browser, reaches the platform through the Alis Build MCP server at mcp.alis.build. It offers SpecIt, server-side RunDefine, RunBuild and RunDeploy, and the skills tools SearchSkills and LoadSkill. The manual's rule: with a shell, use alis; without one, use the MCP server, whose skills tools also handle backend_outdated from alis skills.
Next: Script the CLI with JSON for the full contract, and Agents, skills and the CLI for why it is designed this way.