For the complete documentation index, see llms.txt. This page is also available as Markdown.
iai agents update
Update an agent in a project
Synopsis
Update an agent in a specific project.
Only the flags you pass are applied; everything else is left at its current value.
--file takes a YAML file matching the agent_config schema and replaces the entire agent config in full when provided (no per-field merge). The config schema depends on the agent version — run 'iai agents compatibility-matrix' to find which schema version applies, then 'iai agents schema --schema-version ' to see the expected fields.
When upgrading to a new agent version with a different schema, update your routines and policies first using --schema-version on their create/update commands, then update the agent with the new config and version.
Lists (--env, --secret) replace the entire current list when provided — pass every value you want to keep.
For schedules, passing --schedule-uptime auto-clears any existing downtime, and --schedule-downtime auto-clears any existing uptime. Pass --schedule-timezone alongside either to change the timezone.
Use --clear-env, --clear-secret, --clear-schedule, or --clear-stack-id to remove those configurations entirely.
--clear-env Remove all environment variables from the agent
--clear-schedule Remove the schedule configuration from the agent
--clear-secret Remove all secret references from the agent
--clear-stack-id Remove the agent from its stack
--endpoint Expose the agent at <agent-name>-<project-hash>.interactive.ai
--env stringArray Environment variable (NAME=VALUE); can be repeated
--file string Path to YAML file matching the agent_config schema (run 'iai agents schema' to see it)
-h, --help help for update
--id string Agent type from the marketplace (e.g. interactive-agent)
-o, --organization string Organization name
-p, --project string Project name
--schedule-downtime string When the agent should be scaled down (mutually exclusive with --schedule-uptime). Format: comma-separated entries of DAY_FROM-DAY_TO HH:MM-HH:MM. Example: 'Sat-Sun 00:00-24:00'
--schedule-timezone string IANA timezone for the schedule (e.g. Europe/Berlin, US/Eastern, UTC); required with --schedule-uptime or --schedule-downtime
--schedule-uptime string When the agent should be running (mutually exclusive with --schedule-downtime). Format: comma-separated entries of DAY_FROM-DAY_TO HH:MM-HH:MM. Example: 'Mon-Fri 07:30-20:30'
--secret stringArray Secret to inject as environment variables; can be repeated
--stack-id string Stack ID to assign the agent to
--version string Agent image version to deploy (e.g. 0.0.1)
--api-key string API key for authentication
--cfg-file string Path to YAML config file with organization, project, and optional service definitions
--deployment-hostname string Hostname for the deployment API (default "https://deployment.interactive.ai")
--hostname string Hostname for the API (default "https://app.interactive.ai")