Integrate IaC code via headless-阿里云帮助中心

The headless mode of IaC Code submits tasks through a one-off child process and returns results through standard output and the exit code. It is designed for CI/CD pipelines, scheduled jobs, shell scripts, and backend jobs that do not require a persistent session. This topic describes the process contract between the caller and IaC Code. For full command usage, see the Headless usage documentation.

Prerequisites

You have completed Install and configure IaC Code.
You have verified that the AI model is accessible and your Alibaba Cloud credentials are configured under the same runtime user.
The caller can specify the working directory, separate standard output and standard error, and read the process exit code.

Minimal integration

Run the following command in the project working directory to submit a single query:

iac-code \
  --prompt "Query the ROS stacks in cn-hangzhou and summarize the ones in an abnormal state. Do not perform any write operations." \
  --output-format json \
  --max-turns 20 \
  --permission-mode dont_ask

Caller responsibilities

Project	Requirements
Working directory	Set it explicitly to the IaC project directory. Do not rely on the current directory of the service process.
Input	Use `--prompt` for fixed tasks. Use `--prompt -` to read from standard input for dynamic or long input.
Output	Use `json` for programmatic parsing and `stream-json` for incremental events. Do not merge standard error into standard output.
Exit code	`0` indicates normal completion, `1` indicates an error, and `2` indicates that the maximum number of turns is reached.
Timeout and cancellation	Set an external timeout on the caller side. On cancellation, terminate the child process and record the task status.
Permissions	Non-interactive mode cannot wait for manual approval. Configure precise allow and deny rules in advance.
Logs	Redact credentials, prompts, and tool results, and keep a task identifier that can be correlated.

For input formats, permission parameters, and ready-to-use shell scripts, see Use Headless non-interactive mode.

Integration recommendations

Use a separate process and an explicit working directory for each concurrent task to prevent multiple tasks from modifying the same project files at the same time.
Set upper limits for --max-turns, the process timeout, the number of retries, and the model cost.
Use dont_ask for read-only checks and state in the prompt that no write operations are performed.
Let the upstream approval system decide whether to allow cloud resource changes, and use --allowed-tools to grant precise access to the target API operations.
If you need a long-running subprocess to exchange multi-turn streaming JSON, use the SDK Process Mode described in the GitHub documentation.

If you also need structured permission requests and session lifecycle management, switch to ACP.

FAQ

Standard output is not valid JSON

Make sure that you use --output-format json and that the caller captures stdout and stderr separately. For incremental events, use stream-json instead, and do not parse the output as a single JSON document.

An automated task is denied because of permissions

dont_ask will reject operations that would otherwise require confirmation. For inspection tasks, review the required files or cloud APIs, and configure fine-grained authorization after approvals are completed upstream; do not directly grant access to all tools.

How do I continue a previous task?

One-off tasks can use session recovery parameters, but if the caller needs stable multi-turn sessions, events, and interruption control, ACP should be evaluated first. Remote task collaboration between agents uses A2A.