foundry-agent/routine/references/cli-crud.md
CLI CRUD and Operations
Use azd ai routine for imperative routine CRUD and operations. Every verb accepts --output json or --output table (default), and -p <endpoint> to override the resolved project endpoint.
Vocabulary: CLI aliases vs. manifest values
A routine is a trigger (when it fires) plus an action (what it does). There are two spellings for each type: the CLI flags accept a short alias, while a --file manifest (and azure.yaml) use the raw wire type: value. They mean the same thing.
Triggers
| Fires on | --trigger alias | manifest type: | Key fields |
|----------|-------------------|------------------|------------|
| A single moment (one-shot) | timer | timer | at (ISO 8601 UTC) |
| A recurring cron schedule | recurring | schedule | cron_expression, time_zone |
| A GitHub issue event | github-issue | github_issue | connection_id, owner, repository, issue_event |
| A custom external event | custom | custom | provider, event_name, parameters |
Actions — both invoke the target agent; they differ only in which agent protocol is called and which field resumes prior context.
| Invokes the agent using | --action alias | manifest type: | Resume field |
|-------------------------|------------------|------------------|--------------|
| the agent responses protocol | agent-response (default) | invoke_agent_responses_api | conversation |
| the agent invocations protocol | agent-invoke | invoke_agent_invocations_api | session_id |
Create
Put the prompt or payload the routine sends to the agent in action.input. What it should contain depends on the action type you chose (the --action alias / action type: from the table above): when the action is agent-response (invoke_agent_responses_api), action.input is the natural-language prompt; when the action is agent-invoke (invoke_agent_invocations_api), it is the hosted agent's expected request payload. azd ai routine create has no --input flag, so any routine that needs action.input must be created from a manifest:
# routine.yaml — the type: fields take the manifest value from the table above
triggers:
default:
type: schedule
cron_expression: "0 * * * *"
action:
type: invoke_agent_responses_api
agent_name: my-agent
input: "Say hi."
azd ai routine create hourly-hello --file routine.yaml
Flag-only create works only when the target agent needs no stored input. --file and --trigger are mutually exclusive.
# One-shot timer -> agent
azd ai routine create nightly-report \
--trigger timer --at <YYYY-MM-DDTHH:MM:SSZ> \
--action agent-response --agent-name my-agent
# Recurring cron schedule
azd ai routine create daily-digest \
--trigger recurring --cron "0 8 * * *" --time-zone America/New_York \
--action agent-response --agent-name my-agent \
--description "Daily 8am digest"
# GitHub issue event -> agent
azd ai routine create triage-on-open \
--trigger github-issue \
--connection-id <workspace-connection-id> --owner Azure --repository azure-dev \
--issue-event opened \
--action agent-invoke --agent-name triage-agent
# Custom event -> agent
azd ai routine create on-custom-event \
--trigger custom --provider <provider-id> --event-name <event> \
--parameters '{"key":"value"}' \
--action agent-response --agent-name my-agent
Create Flags
| Flag | Applies to | Notes |
|------|------------|-------|
| --trigger | all | timer | recurring | github-issue | custom (required unless --file) |
| --at | timer | ISO 8601 UTC datetime, e.g. <YYYY-MM-DDTHH:MM:SSZ> |
| --cron | recurring | 5-field cron; minimum interval 5 minutes |
| --time-zone | recurring | IANA zone, e.g. America/New_York (default UTC; not valid for timer) |
| --connection-id, --owner, --repository, --issue-event | github-issue | all four required; --issue-event is opened or closed |
| --provider, --event-name, --parameters | custom | --provider and JSON-object --parameters required |
| --action | all | agent-response (default) | agent-invoke |
| --agent-name | --agent-endpoint-id | action | exactly one; identifies the target agent |
| --conversation-id | agent-response | continue an existing conversation (preview) |
| --session-id | agent-invoke | continue an existing hosted-agent session |
| --description | all | free-text description |
| --enabled | all | enabled by default; pass --enabled=false to create disabled |
| --force | all | overwrite an existing routine of the same name (upsert) |
Read
azd ai routine list
azd ai routine list --output json
azd ai routine show nightly-report
azd ai routine show nightly-report --output json
Update
update changes only the fields you pass; everything else is preserved. Supply named flags and/or a --file manifest.
azd ai routine update daily-digest --cron "30 9 * * *"
azd ai routine update daily-digest --agent-name another-agent --description "New owner"
azd ai routine update daily-digest --file routine.yaml
The trigger and action types are immutable: --trigger / --action are rejected on update. To change a type, delete the routine and recreate it.
Delete
azd ai routine delete daily-digest
azd ai routine delete daily-digest --force
Use --force for non-interactive deletes, including under --no-prompt.
Routine Operations
azd ai routine enable daily-digest
azd ai routine disable daily-digest
# Fire a routine once, now
azd ai routine dispatch daily-digest
azd ai routine dispatch daily-digest --input '{"foo":"bar"}'
azd ai routine dispatch daily-digest --async
# Inspect past runs
azd ai routine run list daily-digest
azd ai routine run list daily-digest --top 20 --filter "<odata-filter>"
dispatch --input is a one-time override for that manual run only; it does not change the routine's stored action.input. dispatch prints a Dispatch ID and Action Correlation ID — use run list to see the resulting status and phase.