From 1fd8db239ace0d99d6320aba19a9a05a345a5ef6 Mon Sep 17 00:00:00 2001
From: Paul Asjes <paul.asjes@elevenlabs.io>
Date: Thu, 12 Nov 2026 11:50:55 +0100
Subject: [PATCH 1/5] feat: agent configs can be YAML or TOML files (1.11.0)

A config file's extension now sets its format: .json, .yaml/.yml or
.toml. Index files stay JSON and their config paths can point at any of
the three. `agents add` and `agents pull` take --config-format for new
files; existing files keep their format, a new branch file follows its
agent's, and `add --from-file` follows the file it read.

TOML has no null, so writing TOML drops null fields. Agents lose nothing,
since push PATCHes, but a TOML config cannot clear a field.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Cargo.lock                               |   2 +-
 Cargo.toml                               |   2 +-
 README.md                                |  14 +-
 cli/elevenlabs/workflow/agents.rs        |  89 +++++-
 cli/elevenlabs/workflow/config_format.rs | 361 +++++++++++++++++++++++
 cli/elevenlabs/workflow/mod.rs           |   1 +
 cli/elevenlabs/workflow/project.rs       |  54 +++-
 cli/elevenlabs/workflow/tests.rs         |   6 +-
 cli/elevenlabs/workflow/tools.rs         |   6 +-
 tests/agents_config_format_test.rs       | 248 ++++++++++++++++
 10 files changed, 741 insertions(+), 42 deletions(-)
 create mode 100644 cli/elevenlabs/workflow/config_format.rs
 create mode 100644 tests/agents_config_format_test.rs

diff --git a/Cargo.lock b/Cargo.lock
index 502144e5..2979765a 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -528,7 +528,7 @@ checksum = "75b325c5dbd37f80359721ad39aca5a29fb04c89279657cffdda8736d0c0b9d2"
 
 [[package]]
 name = "elevenlabs-cli"
-version = "1.10.0"
+version = "1.11.0"
 dependencies = [
  "anyhow",
  "arboard",
diff --git a/Cargo.toml b/Cargo.toml
index 6f5ddc19..3a1c5252 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "elevenlabs-cli"
-version = "1.10.0"
+version = "1.11.0"
 edition = "2021"
 description = "CLI for the ElevenLabs API"
 license = "MIT"
diff --git a/README.md b/README.md
index 2e5ec098..bde5ea0b 100644
--- a/README.md
+++ b/README.md
@@ -169,7 +169,7 @@ For production, prefer setting `webhook` on `create` and handling the webhook ev
 
 ## Agents as Code
 
-Manage Conversational AI agents from local configuration files. `elevenlabs agents init` scaffolds a project; agent configs live as JSON on disk and sync to ElevenLabs. Pulled configs are stored as raw wire JSON and pushed back verbatim, so they round-trip losslessly.
+Manage Conversational AI agents from local configuration files. `elevenlabs agents init` scaffolds a project; agent configs live on disk as JSON, YAML or TOML and sync to ElevenLabs. Pulled configs keep the raw wire fields and are pushed back verbatim, so they round-trip losslessly.
 
 ### Project structure
 
@@ -190,7 +190,7 @@ your_project/
 elevenlabs agents init [path] [--override]
 
 # Create an agent from a template (or an existing file), upload it, and register it
-elevenlabs agents add <name> [--template <template>] [--output-path <path>]
+elevenlabs agents add <name> [--template <template>] [--output-path <path> | --config-format json|yaml|toml]
 elevenlabs agents add [name] --from-file <path>
 
 # Show the status of locally-configured agents
@@ -198,7 +198,7 @@ elevenlabs agents status
 
 # Sync configs with ElevenLabs (push force-overrides main + registered branches)
 elevenlabs agents push [--agent <agent_id>] [--branch <name|id>] [--version-description <text>] [--dry-run]
-elevenlabs agents pull [--agent <agent_id>] [--branch <name|id>] [--all-branches] [--update] [--all] [--dry-run]
+elevenlabs agents pull [--agent <agent_id>] [--branch <name|id>] [--all-branches] [--update] [--all] [--config-format json|yaml|toml] [--dry-run]
 
 # List available agent templates, or print one's full configuration
 elevenlabs agents templates list
@@ -218,6 +218,14 @@ elevenlabs agents graph [config-path|agent_id|name] [--format ascii|mermaid|merm
 elevenlabs agents graph --uses <id|name>
 ```
 
+### Config file formats
+
+A config file's extension sets its format: `.json`, `.yaml`/`.yml` or `.toml`. The registry files (`agents.json`, `tools.json`, `tests.json`) stay JSON, and their `config` paths can point at any of the three, so you can convert a config by hand and update its path.
+
+New files are JSON unless you pick another format. `agents pull --config-format toml` writes new agents as TOML, and a new branch file follows the format of its agent's config. Files that already exist keep their format. `agents add --from-file support.yaml` saves the agent's config as YAML too; `--config-format` overrides that.
+
+TOML has no `null`, so writing TOML drops null fields. For agents nothing is lost: `push` only changes the fields it sends, and a null field was unset already. What TOML can't do is clear a field, because deleting its line leaves the value on ElevenLabs unchanged. To clear one, set it to `null` in a JSON or YAML config.
+
 ### Two surfaces in one namespace
 
 `elevenlabs agents` holds two kinds of command, and it helps to know which you're using:
diff --git a/cli/elevenlabs/workflow/agents.rs b/cli/elevenlabs/workflow/agents.rs
index bccb9e05..bd8f1428 100644
--- a/cli/elevenlabs/workflow/agents.rs
+++ b/cli/elevenlabs/workflow/agents.rs
@@ -15,6 +15,7 @@ use fern_cli_sdk::error::CliError;
 use fern_cli_sdk::openapi::AppContext;
 use serde_json::{json, Value};
 
+use super::config_format::{ConfigFormat, FORMAT_NAMES};
 use super::util::{downcast_ctx, dry_run_flag, opt_string, plan_pull_action, PullAction};
 use super::{api, project, settings, templates, verify};
 
@@ -335,6 +336,10 @@ struct AddArgs {
     /// Create the agent from an existing config file.
     #[arg(long = "from-file")]
     from_file: Option<String>,
+    /// Format of the generated config file. Defaults to the format of
+    /// --from-file, else json. With --output-path, its extension decides.
+    #[arg(long = "config-format", value_parser = FORMAT_NAMES, conflicts_with = "output_path")]
+    config_format: Option<String>,
 }
 
 fn handle_add(args: AddArgs, ctx: &AppContext) -> Result<(), CliError> {
@@ -385,19 +390,39 @@ fn handle_add(args: AddArgs, ctx: &AppContext) -> Result<(), CliError> {
         (cfg, name)
     };
 
-    // Create in ElevenLabs first to obtain an ID.
-    println!("Creating agent '{agent_name}' in ElevenLabs...");
-    let agent_id = api::create_agent(ctx, &agent_config)?;
-    println!("Created agent in ElevenLabs with ID: {agent_id}");
-
     // Resolve the on-disk config path (custom or generated from the name).
     let config_path = match &args.output_path {
         Some(path) => path.clone(),
-        None => project::generate_unique_filename(project::AGENT_CONFIGS_DIR, &agent_name, ".json")
+        None => {
+            let format = args
+                .config_format
+                .as_deref()
+                .and_then(ConfigFormat::from_name)
+                .or_else(|| {
+                    args.from_file
+                        .as_deref()
+                        .map(|f| ConfigFormat::from_path(Path::new(f)))
+                })
+                .unwrap_or(ConfigFormat::Json);
+            project::generate_unique_filename(
+                project::AGENT_CONFIGS_DIR,
+                &agent_name,
+                format.extension(),
+            )
             .display()
-            .to_string(),
+            .to_string()
+        }
     };
-    project::write_json_in_project(&config_path, &agent_config)?;
+    // Render before creating: a config the format can't hold (TOML needs an
+    // object at the top) would otherwise leave a remote agent with no file.
+    ConfigFormat::from_path(Path::new(&config_path)).render(&agent_config)?;
+
+    // Create in ElevenLabs first to obtain an ID.
+    println!("Creating agent '{agent_name}' in ElevenLabs...");
+    let agent_id = api::create_agent(ctx, &agent_config)?;
+    println!("Created agent in ElevenLabs with ID: {agent_id}");
+
+    project::write_config_in_project(&config_path, &agent_config)?;
     match &args.from_file {
         Some(from_file) => println!("Created config file: {config_path} (from: {from_file})"),
         None => println!(
@@ -868,6 +893,15 @@ fn pull_command() -> clap::Command {
                 .default_value("agent_configs")
                 .help("Directory to write config files into"),
         )
+        .arg(
+            clap::Arg::new("config-format")
+                .long("config-format")
+                .value_parser(FORMAT_NAMES)
+                .help(
+                    "Format of newly created config files: json (default), yaml or toml. \
+                     Existing files keep their format; a new branch file follows its agent's",
+                ),
+        )
         .arg(
             clap::Arg::new("update")
                 .long("update")
@@ -895,6 +929,9 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
     let all_branches = matches.get_flag("all-branches");
     let output_dir =
         opt_string(matches, "output-dir").unwrap_or_else(|| "agent_configs".to_string());
+    let config_format = opt_string(matches, "config-format")
+        .as_deref()
+        .and_then(ConfigFormat::from_name);
     let dry_run = dry_run_flag(matches);
     let update = matches.get_flag("update");
     let all = matches.get_flag("all");
@@ -1051,7 +1088,7 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
         let entry_idx = match existing_idx {
             Some(i) => {
                 let cfg_path = registry.agents[*i].config.clone();
-                project::write_json_in_project(&cfg_path, &config)?;
+                project::write_config_in_project(&cfg_path, &config)?;
                 if let Some(v) = &version_id {
                     registry.agents[*i].version_id = Some(v.clone());
                 }
@@ -1062,10 +1099,11 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
                 *i
             }
             None => {
-                let cfg_path = project::generate_unique_filename(&output_dir, name, ".json")
+                let ext = new_config_ext(config_format, None);
+                let cfg_path = project::generate_unique_filename(&output_dir, name, ext)
                     .display()
                     .to_string();
-                project::write_json_in_project(&cfg_path, &config)?;
+                project::write_config_in_project(&cfg_path, &config)?;
                 registry.agents.push(project::AgentDefinition {
                     config: cfg_path.clone(),
                     id: Some(id.clone()),
@@ -1083,11 +1121,11 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
             let branch_path = project::generate_unique_filename(
                 &output_dir,
                 &format!("{name}.{branch}"),
-                ".json",
+                new_config_ext(config_format, Some(&registry.agents[entry_idx].config)),
             )
             .display()
             .to_string();
-            project::write_json_in_project(&branch_path, &config)?;
+            project::write_config_in_project(&branch_path, &config)?;
             let branches = registry.agents[entry_idx]
                 .branches
                 .get_or_insert_with(Default::default);
@@ -1103,7 +1141,15 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
         }
 
         if all_branches {
-            pull_all_branches(ctx, id, name, entry_idx, &mut registry, &output_dir)?;
+            pull_all_branches(
+                ctx,
+                id,
+                name,
+                entry_idx,
+                &mut registry,
+                &output_dir,
+                config_format,
+            )?;
         }
 
         processed += 1;
@@ -1128,6 +1174,15 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
     Ok(())
 }
 
+/// Extension for a config file a pull creates: `--config-format` when given,
+/// else the format of `agent_config` (the agent's main config, so its branch
+/// files match it), else JSON.
+fn new_config_ext(flag: Option<ConfigFormat>, agent_config: Option<&str>) -> &'static str {
+    flag.or_else(|| agent_config.map(|c| ConfigFormat::from_path(Path::new(c))))
+        .unwrap_or(ConfigFormat::Json)
+        .extension()
+}
+
 /// Pull every non-archived, non-main branch for an agent into config files
 /// tracked under its `agents.json` entry. Ports v0's `pullAllBranches`.
 fn pull_all_branches(
@@ -1137,6 +1192,7 @@ fn pull_all_branches(
     entry_idx: usize,
     registry: &mut project::AgentsConfig,
     output_dir: &str,
+    config_format: Option<ConfigFormat>,
 ) -> Result<(), CliError> {
     println!("  Fetching branches for '{agent_name}'...");
     let branches = api::list_branches(ctx, agent_id, false)?;
@@ -1183,11 +1239,12 @@ fn pull_all_branches(
             .and_then(|m| m.get(bname))
             .map(|b| b.config.clone());
         let branch_path = existing_path.unwrap_or_else(|| {
-            project::generate_unique_filename(output_dir, &format!("{agent_name}.{bname}"), ".json")
+            let ext = new_config_ext(config_format, Some(&registry.agents[entry_idx].config));
+            project::generate_unique_filename(output_dir, &format!("{agent_name}.{bname}"), ext)
                 .display()
                 .to_string()
         });
-        project::write_json_in_project(&branch_path, &branch_config)?;
+        project::write_config_in_project(&branch_path, &branch_config)?;
 
         let map = registry.agents[entry_idx]
             .branches
diff --git a/cli/elevenlabs/workflow/config_format.rs b/cli/elevenlabs/workflow/config_format.rs
new file mode 100644
index 00000000..61c854e5
--- /dev/null
+++ b/cli/elevenlabs/workflow/config_format.rs
@@ -0,0 +1,361 @@
+//! On-disk formats for entity config files: JSON, YAML and TOML.
+//!
+//! Configs are held in memory as raw wire JSON ([`Value`], see
+//! [`super::project`]), so each format is only a different rendering of the
+//! same value. The format of a file is picked by its extension; anything that
+//! isn't `.yaml`/`.yml`/`.toml` is JSON, so existing projects read exactly as
+//! before. Index files (`agents.json` & co.) are always JSON.
+//!
+//! TOML has no `null`, so writing TOML drops null fields (and null array
+//! elements). For an agent that loses nothing: `push` sends a PATCH, where a
+//! missing field is left as it is, and a field that pulled as null was unset
+//! already. What TOML can't express is *clearing* a field: deleting its line
+//! leaves the remote value alone. That needs `null` in a JSON or YAML config.
+
+use std::path::Path;
+
+use fern_cli_sdk::error::CliError;
+use serde_json::{Map, Value};
+use toml_edit::{Array, ArrayOfTables, DocumentMut, InlineTable, Item, Table};
+
+/// The format of a config file.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ConfigFormat {
+    Json,
+    Yaml,
+    Toml,
+}
+
+/// Values accepted by `--config-format`.
+pub const FORMAT_NAMES: [&str; 3] = ["json", "yaml", "toml"];
+
+impl ConfigFormat {
+    /// The format a path is read and written in, from its extension.
+    pub fn from_path(path: &Path) -> Self {
+        let ext = path
+            .extension()
+            .and_then(|e| e.to_str())
+            .map(str::to_ascii_lowercase);
+        match ext.as_deref() {
+            Some("yaml" | "yml") => Self::Yaml,
+            Some("toml") => Self::Toml,
+            _ => Self::Json,
+        }
+    }
+
+    /// Parse a `--config-format` value (one of [`FORMAT_NAMES`]).
+    pub fn from_name(name: &str) -> Option<Self> {
+        match name.to_ascii_lowercase().as_str() {
+            "json" => Some(Self::Json),
+            "yaml" | "yml" => Some(Self::Yaml),
+            "toml" => Some(Self::Toml),
+            _ => None,
+        }
+    }
+
+    /// Extension, with its leading dot, for a newly generated config file.
+    pub fn extension(self) -> &'static str {
+        match self {
+            Self::Json => ".json",
+            Self::Yaml => ".yaml",
+            Self::Toml => ".toml",
+        }
+    }
+
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Json => "JSON",
+            Self::Yaml => "YAML",
+            Self::Toml => "TOML",
+        }
+    }
+
+    /// Parse a config file's text.
+    pub fn parse(self, text: &str) -> Result<Value, String> {
+        match self {
+            Self::Json => serde_json::from_str(text).map_err(|e| e.to_string()),
+            Self::Yaml => serde_yaml::from_str(text).map_err(|e| e.to_string()),
+            Self::Toml => {
+                let doc: DocumentMut = text.parse().map_err(|e| format!("{e}"))?;
+                table_to_json(doc.as_table())
+            }
+        }
+    }
+
+    /// Render a config for writing. JSON goes through
+    /// [`super::project::to_pretty_string`] for v0's 4-space indent.
+    pub fn render(self, value: &Value) -> Result<String, CliError> {
+        match self {
+            Self::Json => super::project::to_pretty_string(value),
+            Self::Yaml => serde_yaml::to_string(value)
+                .map_err(|e| CliError::Other(anyhow::anyhow!("Could not serialize YAML: {e}"))),
+            Self::Toml => json_to_toml(value).map_err(CliError::Validation),
+        }
+    }
+}
+
+// ── JSON → TOML ─────────────────────────────────────────────────────
+
+fn json_to_toml(value: &Value) -> Result<String, String> {
+    let Value::Object(map) = value else {
+        return Err("A TOML config must be an object at the top level".to_string());
+    };
+    let mut doc = DocumentMut::new();
+    fill_table(doc.as_table_mut(), map)?;
+    Ok(doc.to_string())
+}
+
+fn fill_table(table: &mut Table, map: &Map<String, Value>) -> Result<(), String> {
+    for (key, value) in map {
+        if let Some(item) = to_item(value)? {
+            table.insert(key, item);
+        }
+    }
+    Ok(())
+}
+
+/// Objects become `[table]` sections and arrays of objects `[[array]]`
+/// sections, which keeps a deeply nested agent config readable. `None` for
+/// null, which TOML can't hold.
+fn to_item(value: &Value) -> Result<Option<Item>, String> {
+    match value {
+        Value::Object(map) => {
+            let mut table = Table::new();
+            fill_table(&mut table, map)?;
+            // An implicit table prints no header of its own when it holds
+            // only subtables. An empty one must keep its header, or the
+            // (empty) object would vanish from the file.
+            table.set_implicit(!map.is_empty());
+            Ok(Some(Item::Table(table)))
+        }
+        Value::Array(items)
+            if items.iter().any(Value::is_object)
+                && items.iter().all(|v| v.is_object() || v.is_null()) =>
+        {
+            let mut tables = ArrayOfTables::new();
+            for map in items.iter().filter_map(Value::as_object) {
+                let mut table = Table::new();
+                fill_table(&mut table, map)?;
+                tables.push(table);
+            }
+            Ok(Some(Item::ArrayOfTables(tables)))
+        }
+        other => Ok(to_value(other)?.map(Item::Value)),
+    }
+}
+
+/// An inline TOML value: used for scalars, and for objects and arrays nested
+/// inside an array that isn't a plain array of objects.
+fn to_value(value: &Value) -> Result<Option<toml_edit::Value>, String> {
+    Ok(Some(match value {
+        Value::Null => return Ok(None),
+        Value::Bool(b) => (*b).into(),
+        Value::Number(n) => match (n.as_i64(), n.as_f64()) {
+            (Some(i), _) => i.into(),
+            // A u64 above i64::MAX would silently lose precision as a float.
+            (None, Some(f)) if n.is_f64() => f.into(),
+            _ => return Err(format!("{n} is too large for a TOML integer")),
+        },
+        Value::String(s) => s.as_str().into(),
+        Value::Array(items) => {
+            let mut array = Array::new();
+            for item in items {
+                if let Some(v) = to_value(item)? {
+                    array.push(v);
+                }
+            }
+            array.into()
+        }
+        Value::Object(map) => {
+            let mut table = InlineTable::new();
+            for (key, item) in map {
+                if let Some(v) = to_value(item)? {
+                    table.insert(key, v);
+                }
+            }
+            table.into()
+        }
+    }))
+}
+
+// ── TOML → JSON ─────────────────────────────────────────────────────
+
+fn table_to_json(table: &Table) -> Result<Value, String> {
+    let mut map = Map::new();
+    for (key, item) in table.iter() {
+        map.insert(key.to_string(), item_to_json(item)?);
+    }
+    Ok(Value::Object(map))
+}
+
+fn item_to_json(item: &Item) -> Result<Value, String> {
+    match item {
+        Item::None => Ok(Value::Null),
+        Item::Value(v) => value_to_json(v),
+        Item::Table(t) => table_to_json(t),
+        Item::ArrayOfTables(tables) => tables.iter().map(table_to_json).collect(),
+    }
+}
+
+fn value_to_json(value: &toml_edit::Value) -> Result<Value, String> {
+    use toml_edit::Value as T;
+    Ok(match value {
+        T::String(s) => Value::String(s.value().clone()),
+        T::Integer(i) => (*i.value()).into(),
+        T::Float(f) => serde_json::Number::from_f64(*f.value())
+            .map(Value::Number)
+            .ok_or_else(|| format!("{} has no JSON equivalent", f.value()))?,
+        T::Boolean(b) => Value::Bool(*b.value()),
+        // The API has no datetime type: it takes these as strings.
+        T::Datetime(d) => Value::String(d.value().to_string()),
+        T::Array(items) => items.iter().map(value_to_json).collect::<Result<_, _>>()?,
+        T::InlineTable(table) => {
+            let mut map = Map::new();
+            for (key, v) in table.iter() {
+                map.insert(key.to_string(), value_to_json(v)?);
+            }
+            Value::Object(map)
+        }
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn sample() -> Value {
+        json!({
+            "name": "Support",
+            "tags": ["a", "b"],
+            "conversation_config": {
+                "agent": {
+                    "first_message": "Hi!",
+                    "prompt": {
+                        "prompt": "Line one\nLine \"two\"",
+                        "temperature": 0.5,
+                        "tool_ids": [],
+                        "tools": [
+                            {"name": "lookup", "params": {"retries": 3}},
+                            {"name": "end_call", "params": {}}
+                        ]
+                    }
+                },
+                "tts": {"voice_id": "abc", "stability": 1, "enabled": true}
+            },
+            "platform_settings": {},
+            "mixed": [1, "two", {"three": 3}, [4]]
+        })
+    }
+
+    #[test]
+    fn format_follows_the_extension() {
+        assert_eq!(
+            ConfigFormat::from_path(Path::new("a/b.json")),
+            ConfigFormat::Json
+        );
+        assert_eq!(
+            ConfigFormat::from_path(Path::new("a/b.yaml")),
+            ConfigFormat::Yaml
+        );
+        assert_eq!(
+            ConfigFormat::from_path(Path::new("a/b.YML")),
+            ConfigFormat::Yaml
+        );
+        assert_eq!(
+            ConfigFormat::from_path(Path::new("a/b.toml")),
+            ConfigFormat::Toml
+        );
+        // No extension, or an unknown one, stays JSON as it always was.
+        assert_eq!(
+            ConfigFormat::from_path(Path::new("a/b")),
+            ConfigFormat::Json
+        );
+        assert_eq!(
+            ConfigFormat::from_path(Path::new("a/b.txt")),
+            ConfigFormat::Json
+        );
+    }
+
+    #[test]
+    fn every_name_parses_and_round_trips_its_extension() {
+        for name in FORMAT_NAMES {
+            let format = ConfigFormat::from_name(name).expect(name);
+            let path = format!("x{}", format.extension());
+            assert_eq!(ConfigFormat::from_path(Path::new(&path)), format);
+        }
+        assert_eq!(ConfigFormat::from_name("xml"), None);
+    }
+
+    #[test]
+    fn yaml_and_toml_round_trip_losslessly() {
+        for format in [ConfigFormat::Json, ConfigFormat::Yaml, ConfigFormat::Toml] {
+            let rendered = format.render(&sample()).unwrap();
+            let parsed = format.parse(&rendered).unwrap();
+            assert_eq!(parsed, sample(), "{format:?}:\n{rendered}");
+        }
+    }
+
+    #[test]
+    fn toml_uses_sections_for_nested_objects() {
+        let rendered = ConfigFormat::Toml.render(&sample()).unwrap();
+        assert!(rendered.contains("[conversation_config.tts]"), "{rendered}");
+        assert!(
+            rendered.contains("[[conversation_config.agent.prompt.tools]]"),
+            "{rendered}"
+        );
+        // Only-subtables parents print no header of their own.
+        assert!(!rendered.contains("[conversation_config]\n"), "{rendered}");
+        // An empty object keeps its header so it survives the round trip.
+        assert!(rendered.contains("[platform_settings]"), "{rendered}");
+    }
+
+    #[test]
+    fn toml_drops_nulls() {
+        let value = json!({
+            "name": "x",
+            "language": null,
+            "nested": {"keep": 1, "drop": null},
+            "list": [1, null, 2],
+            "tables": [{"a": 1}, null]
+        });
+        let rendered = ConfigFormat::Toml.render(&value).unwrap();
+        assert_eq!(
+            ConfigFormat::Toml.parse(&rendered).unwrap(),
+            json!({
+                "name": "x",
+                "nested": {"keep": 1},
+                "list": [1, 2],
+                "tables": [{"a": 1}]
+            })
+        );
+    }
+
+    #[test]
+    fn toml_rejects_what_it_cannot_hold() {
+        assert!(ConfigFormat::Toml.render(&json!([1, 2])).is_err());
+        assert!(ConfigFormat::Toml
+            .render(&json!({"big": u64::MAX}))
+            .unwrap_err()
+            .to_string()
+            .contains("too large"));
+        assert!(ConfigFormat::Toml.parse("x = nan").is_err());
+    }
+
+    #[test]
+    fn toml_datetimes_read_as_strings() {
+        assert_eq!(
+            ConfigFormat::Toml
+                .parse("at = 2026-01-02T03:04:05Z")
+                .unwrap(),
+            json!({"at": "2026-01-02T03:04:05Z"})
+        );
+    }
+
+    #[test]
+    fn parse_errors_are_reported() {
+        assert!(ConfigFormat::Json.parse("{").is_err());
+        assert!(ConfigFormat::Yaml.parse("a: [").is_err());
+        assert!(ConfigFormat::Toml.parse("a = ").is_err());
+    }
+}
diff --git a/cli/elevenlabs/workflow/mod.rs b/cli/elevenlabs/workflow/mod.rs
index 6734ba63..9bd9f679 100644
--- a/cli/elevenlabs/workflow/mod.rs
+++ b/cli/elevenlabs/workflow/mod.rs
@@ -16,6 +16,7 @@ use fern_cli_sdk::app::CliApp;
 mod agents;
 mod api;
 mod components;
+mod config_format;
 mod diagram;
 mod feedback;
 mod flows_wait;
diff --git a/cli/elevenlabs/workflow/project.rs b/cli/elevenlabs/workflow/project.rs
index 7109887b..c0fdac3e 100644
--- a/cli/elevenlabs/workflow/project.rs
+++ b/cli/elevenlabs/workflow/project.rs
@@ -13,6 +13,8 @@
 //!   working.
 //! * Files are written pretty-printed with a 4-space indent to match v0's
 //!   `JSON.stringify(value, null, 4)` on-disk format.
+//! * Config files may also be YAML or TOML, picked by their extension (see
+//!   [`super::config_format`]). Index files are always JSON.
 
 #![allow(dead_code)]
 
@@ -23,6 +25,8 @@ use fern_cli_sdk::error::CliError;
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
+use super::config_format::ConfigFormat;
+
 // ── Index-file locations ────────────────────────────────────────────
 
 pub const AGENTS_FILE: &str = "agents.json";
@@ -267,9 +271,10 @@ pub fn read_value_in_project(path_str: &str) -> Result<Value, CliError> {
     read_value(&path)
 }
 
-/// Write a config file named by an index file, with containment + symlink checks.
-pub fn write_json_in_project<T: Serialize>(path_str: &str, value: &T) -> Result<(), CliError> {
-    write_json(&resolve_in_project(path_str)?, value)
+/// Write a config file named by an index file, with containment + symlink
+/// checks, in the format its extension names.
+pub fn write_config_in_project(path_str: &str, value: &Value) -> Result<(), CliError> {
+    write_config(&resolve_in_project(path_str)?, value)
 }
 
 /// Delete a config file named by an index file, with containment + symlink
@@ -302,14 +307,10 @@ fn restrict_permissions(file: &std::fs::File) {
     let _ = file;
 }
 
-// ── JSON IO ─────────────────────────────────────────────────────────
+// ── Config IO ───────────────────────────────────────────────────────
 
-/// Read and deserialize a JSON file, with v0-style error messages.
-pub fn read_json<T>(path: &Path) -> Result<T, CliError>
-where
-    T: serde::de::DeserializeOwned,
-{
-    let data = std::fs::read_to_string(path).map_err(|e| {
+fn read_text(path: &Path) -> Result<String, CliError> {
+    std::fs::read_to_string(path).map_err(|e| {
         if e.kind() == std::io::ErrorKind::NotFound {
             CliError::Validation(format!(
                 "Configuration file not found at {}",
@@ -318,8 +319,15 @@ where
         } else {
             CliError::Other(anyhow::anyhow!("Could not read {}: {e}", path.display()))
         }
-    })?;
-    serde_json::from_str(&data).map_err(|e| {
+    })
+}
+
+/// Read and deserialize a JSON file, with v0-style error messages.
+pub fn read_json<T>(path: &Path) -> Result<T, CliError>
+where
+    T: serde::de::DeserializeOwned,
+{
+    serde_json::from_str(&read_text(path)?).map_err(|e| {
         CliError::Validation(format!(
             "Invalid JSON in configuration file {}: {e}",
             path.display()
@@ -327,9 +335,17 @@ where
     })
 }
 
-/// Read a config file as an untyped [`Value`] (lossless).
+/// Read a config file as an untyped [`Value`] (lossless), in the JSON, YAML
+/// or TOML format its extension names.
 pub fn read_value(path: &Path) -> Result<Value, CliError> {
-    read_json::<Value>(path)
+    let format = ConfigFormat::from_path(path);
+    format.parse(&read_text(path)?).map_err(|e| {
+        CliError::Validation(format!(
+            "Invalid {} in configuration file {}: {e}",
+            format.label(),
+            path.display()
+        ))
+    })
 }
 
 /// Serialize with a 4-space indent to match v0's on-disk format.
@@ -351,6 +367,15 @@ pub fn to_pretty_string<T: Serialize>(value: &T) -> Result<String, CliError> {
 /// guarantee holds even for paths that don't come from an index file (`init`
 /// writing `agents.json`, for instance).
 pub fn write_json<T: Serialize>(path: &Path, value: &T) -> Result<(), CliError> {
+    write_text(path, &to_pretty_string(value)?)
+}
+
+/// Write a config in the JSON, YAML or TOML format its extension names.
+pub fn write_config(path: &Path, value: &Value) -> Result<(), CliError> {
+    write_text(path, &ConfigFormat::from_path(path).render(value)?)
+}
+
+fn write_text(path: &Path, rendered: &str) -> Result<(), CliError> {
     use std::io::Write;
     if let Some(parent) = path.parent() {
         if !parent.as_os_str().is_empty() {
@@ -362,7 +387,6 @@ pub fn write_json<T: Serialize>(path: &Path, value: &T) -> Result<(), CliError>
             })?;
         }
     }
-    let rendered = to_pretty_string(value)?;
     let mut file = create_no_follow(path)?;
     restrict_permissions(&file);
     file.write_all(rendered.as_bytes()).map_err(|e| {
diff --git a/cli/elevenlabs/workflow/tests.rs b/cli/elevenlabs/workflow/tests.rs
index c4d9a7c3..9b474540 100644
--- a/cli/elevenlabs/workflow/tests.rs
+++ b/cli/elevenlabs/workflow/tests.rs
@@ -304,7 +304,7 @@ fn handle_add(args: AddArgs, ctx: &AppContext) -> Result<(), CliError> {
             .display()
             .to_string(),
     };
-    project::write_json_in_project(&config_path, &config)?;
+    project::write_config_in_project(&config_path, &config)?;
     println!(
         "Created config file: {config_path} (template: {})",
         args.template
@@ -719,14 +719,14 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
         match existing_idx {
             Some(i) => {
                 let cfg_path = registry.tests[*i].config.clone();
-                project::write_json_in_project(&cfg_path, &config)?;
+                project::write_config_in_project(&cfg_path, &config)?;
                 println!("  ✓ Updated '{name}' (config: {cfg_path})");
             }
             None => {
                 let cfg_path = project::generate_unique_filename(&output_dir, name, ".json")
                     .display()
                     .to_string();
-                project::write_json_in_project(&cfg_path, &config)?;
+                project::write_config_in_project(&cfg_path, &config)?;
                 registry.tests.push(project::TestDefinition {
                     config: cfg_path.clone(),
                     test_type,
diff --git a/cli/elevenlabs/workflow/tools.rs b/cli/elevenlabs/workflow/tools.rs
index a87c4d79..3c5c698b 100644
--- a/cli/elevenlabs/workflow/tools.rs
+++ b/cli/elevenlabs/workflow/tools.rs
@@ -153,7 +153,7 @@ fn handle_add(args: AddArgs, ctx: &AppContext) -> Result<(), CliError> {
             .display()
             .to_string(),
     };
-    project::write_json_in_project(&config_path, &config)?;
+    project::write_config_in_project(&config_path, &config)?;
     println!("Created config file: {config_path}");
 
     registry.tools.push(project::ToolDefinition {
@@ -561,14 +561,14 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
         match existing_idx {
             Some(i) => {
                 let cfg_path = registry.tools[*i].config.clone();
-                project::write_json_in_project(&cfg_path, &tool_config)?;
+                project::write_config_in_project(&cfg_path, &tool_config)?;
                 println!("  ✓ Updated '{name}' (config: {cfg_path})");
             }
             None => {
                 let cfg_path = project::generate_unique_filename(&output_dir, name, ".json")
                     .display()
                     .to_string();
-                project::write_json_in_project(&cfg_path, &tool_config)?;
+                project::write_config_in_project(&cfg_path, &tool_config)?;
                 registry.tools.push(project::ToolDefinition {
                     tool_type: tool_type.clone(),
                     config: cfg_path.clone(),
diff --git a/tests/agents_config_format_test.rs b/tests/agents_config_format_test.rs
new file mode 100644
index 00000000..95fa2594
--- /dev/null
+++ b/tests/agents_config_format_test.rs
@@ -0,0 +1,248 @@
+//! Integration tests for YAML and TOML agent config files: `agents pull`,
+//! `push` and `add` against a local mock API. The conversions themselves are
+//! unit-tested in `cli/elevenlabs/workflow/config_format.rs`.
+
+use std::path::Path;
+use std::process::Output;
+
+use serde_json::{json, Value};
+use wiremock::matchers::{method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+const KEY: &str = "sk_0123456789abcdef0123456789abcdef01234567";
+
+fn cli(dir: &Path, server: &str, args: &[&str]) -> Output {
+    let mut cmd = std::process::Command::new(env!("CARGO_BIN_EXE_elevenlabs"));
+    cmd.args(["--base-url", server])
+        .args(args)
+        .current_dir(dir)
+        .env("HOME", dir)
+        .env("TMPDIR", dir)
+        .env_remove("XDG_CONFIG_HOME")
+        .env_remove("APPDATA")
+        .env("NO_COLOR", "1")
+        .env("FERN_CLI_CREDENTIAL_STORE", "file")
+        .env("ELEVENLABS_API_KEY", KEY)
+        .env("ELEVENLABS_TELEMETRY", "0");
+    for var in ["ELEVENLABS_BASE_URL", "ELEVENLABS_VIA", "ELEVENLABS_OUTPUT"] {
+        cmd.env_remove(var);
+    }
+    cmd.output().expect("failed to spawn the elevenlabs binary")
+}
+
+fn ok(out: Output, what: &str) -> String {
+    let text = format!(
+        "{}{}",
+        String::from_utf8_lossy(&out.stdout),
+        String::from_utf8_lossy(&out.stderr)
+    );
+    assert!(out.status.success(), "{what} failed:\n{text}");
+    text
+}
+
+/// A live agent as the API returns it, nulls included.
+fn live_agent() -> Value {
+    json!({
+        "agent_id": "agent_1",
+        "name": "Support",
+        "conversation_config": {
+            "agent": {
+                "first_message": "Hi, how can I help?",
+                "language": null,
+                "prompt": {
+                    "prompt": "You are a support agent.\nBe brief.",
+                    "llm": "gemini-2.5-flash",
+                    "temperature": 0.3,
+                    "tool_ids": ["tool_1"]
+                }
+            },
+            "tts": {"voice_id": "voice_1", "stability": 0.5}
+        },
+        "platform_settings": {"testing": {"attached_tests": [{"test_id": "test_1"}]}},
+        "tags": ["support"]
+    })
+}
+
+async fn serve_agent(server: &MockServer) {
+    Mock::given(method("GET"))
+        .and(path("/v1/convai/agents/agent_1"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(live_agent()))
+        .mount(server)
+        .await;
+}
+
+fn registered_config(dir: &Path) -> String {
+    let index: Value =
+        serde_json::from_str(&std::fs::read_to_string(dir.join("agents.json")).unwrap()).unwrap();
+    index["agents"][0]["config"].as_str().unwrap().to_string()
+}
+
+fn last_body(requests: &[wiremock::Request], verb: &str) -> Value {
+    let req = requests
+        .iter()
+        .rev()
+        .find(|r| r.method.as_str() == verb)
+        .unwrap_or_else(|| panic!("no {verb} request was sent"));
+    serde_json::from_slice(&req.body).unwrap()
+}
+
+#[tokio::test]
+async fn pull_writes_toml_and_push_sends_it_back() {
+    let server = MockServer::start().await;
+    serve_agent(&server).await;
+    Mock::given(method("PATCH"))
+        .and(path("/v1/convai/agents/agent_1"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({"agent_id": "agent_1"})))
+        .mount(&server)
+        .await;
+
+    let dir = tempfile::tempdir().unwrap();
+    let dir = dir.path();
+    ok(cli(dir, &server.uri(), &["agents", "init"]), "init");
+    ok(
+        cli(
+            dir,
+            &server.uri(),
+            &[
+                "agents",
+                "pull",
+                "--agent",
+                "agent_1",
+                "--config-format",
+                "toml",
+                "--yes",
+            ],
+        ),
+        "pull",
+    );
+
+    let config = registered_config(dir);
+    assert!(config.ends_with("Support.toml"), "{config}");
+    let text = std::fs::read_to_string(dir.join(&config)).unwrap();
+    assert!(
+        text.contains("[conversation_config.agent.prompt]"),
+        "{text}"
+    );
+    assert!(
+        text.contains("[[platform_settings.testing.attached_tests]]"),
+        "{text}"
+    );
+    assert!(
+        !text.contains("language"),
+        "nulls are left out of TOML:\n{text}"
+    );
+
+    ok(cli(dir, &server.uri(), &["agents", "push"]), "push");
+    let body = last_body(&server.received_requests().await.unwrap(), "PATCH");
+    let mut expected = live_agent();
+    expected["conversation_config"]["agent"]
+        .as_object_mut()
+        .unwrap()
+        .remove("language");
+    for key in ["conversation_config", "platform_settings", "tags", "name"] {
+        assert_eq!(body[key], expected[key], "{key}");
+    }
+}
+
+#[tokio::test]
+async fn pull_keeps_an_existing_files_format() {
+    let server = MockServer::start().await;
+    serve_agent(&server).await;
+
+    let dir = tempfile::tempdir().unwrap();
+    let dir = dir.path();
+    ok(cli(dir, &server.uri(), &["agents", "init"]), "init");
+    std::fs::write(
+        dir.join("agents.json"),
+        r#"{"agents": [{"config": "agent_configs/support.yaml", "id": "agent_1"}]}"#,
+    )
+    .unwrap();
+    // Asking for TOML only applies to new files.
+    ok(
+        cli(
+            dir,
+            &server.uri(),
+            &[
+                "agents",
+                "pull",
+                "--all",
+                "--agent",
+                "agent_1",
+                "--config-format",
+                "toml",
+                "--yes",
+            ],
+        ),
+        "pull",
+    );
+    let text = std::fs::read_to_string(dir.join("agent_configs/support.yaml")).unwrap();
+    let parsed: Value = serde_yaml::from_str(&text).unwrap();
+    assert_eq!(
+        parsed["conversation_config"],
+        live_agent()["conversation_config"]
+    );
+    assert!(!dir.join("agent_configs/Support.toml").exists());
+}
+
+#[tokio::test]
+async fn add_from_a_yaml_file_creates_a_yaml_config() {
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/v1/convai/agents/create"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({"agent_id": "agent_2"})))
+        .mount(&server)
+        .await;
+
+    let dir = tempfile::tempdir().unwrap();
+    let dir = dir.path();
+    ok(cli(dir, &server.uri(), &["agents", "init"]), "init");
+    std::fs::write(
+        dir.join("support.yml"),
+        "name: Support\nconversation_config:\n  agent:\n    first_message: Hello\ntags: [a]\n",
+    )
+    .unwrap();
+    ok(
+        cli(
+            dir,
+            &server.uri(),
+            &["agents", "add", "--from-file", "support.yml"],
+        ),
+        "add",
+    );
+
+    let body = last_body(&server.received_requests().await.unwrap(), "POST");
+    assert_eq!(
+        body["conversation_config"]["agent"]["first_message"],
+        "Hello"
+    );
+    assert_eq!(body["tags"], json!(["a"]));
+
+    let config = registered_config(dir);
+    assert!(config.ends_with("Support.yaml"), "{config}");
+    let parsed: Value =
+        serde_yaml::from_str(&std::fs::read_to_string(dir.join(&config)).unwrap()).unwrap();
+    assert_eq!(parsed["name"], "Support");
+}
+
+#[test]
+fn a_bad_toml_config_names_the_format() {
+    let dir = tempfile::tempdir().unwrap();
+    let dir = dir.path();
+    std::fs::write(dir.join("broken.toml"), "name = ").unwrap();
+    let out = cli(
+        dir,
+        "http://127.0.0.1:9",
+        &["agents", "workflow", "diagram", "broken.toml"],
+    );
+    assert!(!out.status.success());
+    // Errors print as JSON on stdout when it isn't a terminal.
+    let text = format!(
+        "{}{}",
+        String::from_utf8_lossy(&out.stdout),
+        String::from_utf8_lossy(&out.stderr)
+    );
+    assert!(
+        text.contains("Invalid TOML in configuration file"),
+        "{text}"
+    );
+}

From aee4045919a4a05b1ed6aa3dfbbbdc6cf71ecdd8 Mon Sep 17 00:00:00 2001
From: Paul Asjes <paul.asjes@elevenlabs.io>
Date: Thu, 12 Nov 2026 13:10:48 +0100
Subject: [PATCH 2/5] fix: keep null-only objects and branch files, refuse
 nulls in TOML arrays

- An object whose fields are all null rendered as an implicit, empty
  table and vanished from the TOML file. Decide the header from the
  filled table, so it round-trips as {}.
- A null array element is data (a tool's constant value, say), not an
  unset field, so dropping it changed what push sends. Writing TOML now
  refuses, naming the field and pointing at JSON or YAML.
- `pull --branch` always made a new branch file, leaving the registered
  one stale and, with --config-format, switching its format. It now
  reuses the file registered under that branch's name or ID.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                                |   2 +-
 cli/elevenlabs/workflow/agents.rs        |  30 +++++--
 cli/elevenlabs/workflow/config_format.rs | 102 ++++++++++++++++-------
 tests/agents_config_format_test.rs       |  66 +++++++++++++++
 4 files changed, 160 insertions(+), 40 deletions(-)

diff --git a/README.md b/README.md
index bde5ea0b..5b33c548 100644
--- a/README.md
+++ b/README.md
@@ -224,7 +224,7 @@ A config file's extension sets its format: `.json`, `.yaml`/`.yml` or `.toml`. T
 
 New files are JSON unless you pick another format. `agents pull --config-format toml` writes new agents as TOML, and a new branch file follows the format of its agent's config. Files that already exist keep their format. `agents add --from-file support.yaml` saves the agent's config as YAML too; `--config-format` overrides that.
 
-TOML has no `null`, so writing TOML drops null fields. For agents nothing is lost: `push` only changes the fields it sends, and a null field was unset already. What TOML can't do is clear a field, because deleting its line leaves the value on ElevenLabs unchanged. To clear one, set it to `null` in a JSON or YAML config.
+TOML has no `null`, so writing TOML drops null fields. For agents nothing is lost: `push` only changes the fields it sends, and a null field was unset already. What TOML can't do is clear a field, because deleting its line leaves the value on ElevenLabs unchanged. To clear one, set it to `null` in a JSON or YAML config. A `null` inside a list is data rather than an unset field, so a config with one can't be saved as TOML; the CLI says so and names the field.
 
 ### Two surfaces in one namespace
 
diff --git a/cli/elevenlabs/workflow/agents.rs b/cli/elevenlabs/workflow/agents.rs
index bd8f1428..15bfc991 100644
--- a/cli/elevenlabs/workflow/agents.rs
+++ b/cli/elevenlabs/workflow/agents.rs
@@ -1118,19 +1118,33 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
 
         // --branch: persist the branch config alongside the main one.
         if let (Some(branch), Some(bid)) = (&branch, &branch_id) {
-            let branch_path = project::generate_unique_filename(
-                &output_dir,
-                &format!("{name}.{branch}"),
-                new_config_ext(config_format, Some(&registry.agents[entry_idx].config)),
-            )
-            .display()
-            .to_string();
+            // A branch pulled before keeps its file (and so its format), found
+            // by the name or ID it was registered under, rather than gaining a
+            // second file next to a stale one.
+            let registered = registry.agents[entry_idx].branches.as_ref().and_then(|m| {
+                m.iter()
+                    .find(|(key, def)| *key == branch || def.branch_id == *bid)
+                    .map(|(key, def)| (key.clone(), def.config.clone()))
+            });
+            let (branch_key, branch_path) = match registered {
+                Some(found) => found,
+                None => (
+                    branch.clone(),
+                    project::generate_unique_filename(
+                        &output_dir,
+                        &format!("{name}.{branch}"),
+                        new_config_ext(config_format, Some(&registry.agents[entry_idx].config)),
+                    )
+                    .display()
+                    .to_string(),
+                ),
+            };
             project::write_config_in_project(&branch_path, &config)?;
             let branches = registry.agents[entry_idx]
                 .branches
                 .get_or_insert_with(Default::default);
             branches.insert(
-                branch.clone(),
+                branch_key,
                 project::BranchDefinition {
                     config: branch_path.clone(),
                     branch_id: bid.clone(),
diff --git a/cli/elevenlabs/workflow/config_format.rs b/cli/elevenlabs/workflow/config_format.rs
index 61c854e5..5368e46a 100644
--- a/cli/elevenlabs/workflow/config_format.rs
+++ b/cli/elevenlabs/workflow/config_format.rs
@@ -6,11 +6,13 @@
 //! isn't `.yaml`/`.yml`/`.toml` is JSON, so existing projects read exactly as
 //! before. Index files (`agents.json` & co.) are always JSON.
 //!
-//! TOML has no `null`, so writing TOML drops null fields (and null array
-//! elements). For an agent that loses nothing: `push` sends a PATCH, where a
-//! missing field is left as it is, and a field that pulled as null was unset
-//! already. What TOML can't express is *clearing* a field: deleting its line
-//! leaves the remote value alone. That needs `null` in a JSON or YAML config.
+//! TOML has no `null`, so writing TOML drops null fields. For an agent that
+//! loses nothing: `push` sends a PATCH, where a missing field is left as it
+//! is, and a field that pulled as null was unset already. What TOML can't
+//! express is *clearing* a field: deleting its line leaves the remote value
+//! alone. That needs `null` in a JSON or YAML config. A null array element is
+//! data rather than an unset field, so a config with one can't be written as
+//! TOML at all.
 
 use std::path::Path;
 
@@ -101,52 +103,68 @@ fn json_to_toml(value: &Value) -> Result<String, String> {
         return Err("A TOML config must be an object at the top level".to_string());
     };
     let mut doc = DocumentMut::new();
-    fill_table(doc.as_table_mut(), map)?;
+    fill_table(doc.as_table_mut(), map, "")?;
     Ok(doc.to_string())
 }
 
-fn fill_table(table: &mut Table, map: &Map<String, Value>) -> Result<(), String> {
+/// `path` is the dotted key path of `map`, for error messages.
+fn fill_table(table: &mut Table, map: &Map<String, Value>, path: &str) -> Result<(), String> {
     for (key, value) in map {
-        if let Some(item) = to_item(value)? {
+        if let Some(item) = to_item(value, &join(path, key))? {
             table.insert(key, item);
         }
     }
     Ok(())
 }
 
+fn join(path: &str, key: &str) -> String {
+    if path.is_empty() {
+        key.to_string()
+    } else {
+        format!("{path}.{key}")
+    }
+}
+
+/// A null in an array is data (a constant value, say), not an unset field:
+/// dropping it would change what `push` sends, so refuse instead.
+fn null_in_array(path: &str) -> String {
+    format!(
+        "{path} holds a null in an array, which TOML can't represent. \
+         Use a JSON or YAML config for this one"
+    )
+}
+
 /// Objects become `[table]` sections and arrays of objects `[[array]]`
 /// sections, which keeps a deeply nested agent config readable. `None` for
-/// null, which TOML can't hold.
-fn to_item(value: &Value) -> Result<Option<Item>, String> {
+/// a null field, which TOML can't hold.
+fn to_item(value: &Value, path: &str) -> Result<Option<Item>, String> {
     match value {
         Value::Object(map) => {
             let mut table = Table::new();
-            fill_table(&mut table, map)?;
+            fill_table(&mut table, map, path)?;
             // An implicit table prints no header of its own when it holds
             // only subtables. An empty one must keep its header, or the
-            // (empty) object would vanish from the file.
-            table.set_implicit(!map.is_empty());
+            // (empty) object would vanish from the file. Checked after
+            // filling, since an object of nulls ends up empty too.
+            table.set_implicit(!table.is_empty());
             Ok(Some(Item::Table(table)))
         }
-        Value::Array(items)
-            if items.iter().any(Value::is_object)
-                && items.iter().all(|v| v.is_object() || v.is_null()) =>
-        {
+        Value::Array(items) if !items.is_empty() && items.iter().all(Value::is_object) => {
             let mut tables = ArrayOfTables::new();
-            for map in items.iter().filter_map(Value::as_object) {
+            for (i, map) in items.iter().filter_map(Value::as_object).enumerate() {
                 let mut table = Table::new();
-                fill_table(&mut table, map)?;
+                fill_table(&mut table, map, &format!("{path}[{i}]"))?;
                 tables.push(table);
             }
             Ok(Some(Item::ArrayOfTables(tables)))
         }
-        other => Ok(to_value(other)?.map(Item::Value)),
+        other => Ok(to_value(other, path)?.map(Item::Value)),
     }
 }
 
 /// An inline TOML value: used for scalars, and for objects and arrays nested
 /// inside an array that isn't a plain array of objects.
-fn to_value(value: &Value) -> Result<Option<toml_edit::Value>, String> {
+fn to_value(value: &Value, path: &str) -> Result<Option<toml_edit::Value>, String> {
     Ok(Some(match value {
         Value::Null => return Ok(None),
         Value::Bool(b) => (*b).into(),
@@ -154,14 +172,15 @@ fn to_value(value: &Value) -> Result<Option<toml_edit::Value>, String> {
             (Some(i), _) => i.into(),
             // A u64 above i64::MAX would silently lose precision as a float.
             (None, Some(f)) if n.is_f64() => f.into(),
-            _ => return Err(format!("{n} is too large for a TOML integer")),
+            _ => return Err(format!("{path}: {n} is too large for a TOML integer")),
         },
         Value::String(s) => s.as_str().into(),
         Value::Array(items) => {
             let mut array = Array::new();
-            for item in items {
-                if let Some(v) = to_value(item)? {
-                    array.push(v);
+            for (i, item) in items.iter().enumerate() {
+                match to_value(item, &format!("{path}[{i}]"))? {
+                    Some(v) => array.push(v),
+                    None => return Err(null_in_array(path)),
                 }
             }
             array.into()
@@ -169,7 +188,7 @@ fn to_value(value: &Value) -> Result<Option<toml_edit::Value>, String> {
         Value::Object(map) => {
             let mut table = InlineTable::new();
             for (key, item) in map {
-                if let Some(v) = to_value(item)? {
+                if let Some(v) = to_value(item, &join(path, key))? {
                     table.insert(key, v);
                 }
             }
@@ -311,13 +330,13 @@ mod tests {
     }
 
     #[test]
-    fn toml_drops_nulls() {
+    fn toml_drops_null_fields() {
         let value = json!({
             "name": "x",
             "language": null,
             "nested": {"keep": 1, "drop": null},
-            "list": [1, null, 2],
-            "tables": [{"a": 1}, null]
+            "only_nulls": {"drop": null},
+            "tables": [{"a": 1, "b": null}]
         });
         let rendered = ConfigFormat::Toml.render(&value).unwrap();
         assert_eq!(
@@ -325,12 +344,33 @@ mod tests {
             json!({
                 "name": "x",
                 "nested": {"keep": 1},
-                "list": [1, 2],
+                // Kept as an empty object rather than vanishing.
+                "only_nulls": {},
                 "tables": [{"a": 1}]
-            })
+            }),
+            "{rendered}"
         );
     }
 
+    #[test]
+    fn toml_refuses_nulls_in_arrays() {
+        // A null array element is data, so dropping it would change the
+        // config: a tool's constant value, for instance.
+        for value in [
+            json!({"tool": {"constant_value": [1, null, 2]}}),
+            json!({"tables": [{"a": 1}, null]}),
+            json!({"nested": [[null]]}),
+        ] {
+            let err = ConfigFormat::Toml.render(&value).unwrap_err().to_string();
+            assert!(err.contains("Use a JSON or YAML config"), "{err}");
+        }
+        let err = ConfigFormat::Toml
+            .render(&json!({"tool": {"constant_value": [1, null]}}))
+            .unwrap_err()
+            .to_string();
+        assert!(err.starts_with("tool.constant_value holds a null"), "{err}");
+    }
+
     #[test]
     fn toml_rejects_what_it_cannot_hold() {
         assert!(ConfigFormat::Toml.render(&json!([1, 2])).is_err());
diff --git a/tests/agents_config_format_test.rs b/tests/agents_config_format_test.rs
index 95fa2594..8794e486 100644
--- a/tests/agents_config_format_test.rs
+++ b/tests/agents_config_format_test.rs
@@ -184,6 +184,72 @@ async fn pull_keeps_an_existing_files_format() {
     assert!(!dir.join("agent_configs/Support.toml").exists());
 }
 
+#[tokio::test]
+async fn pull_reuses_a_registered_branch_file() {
+    let server = MockServer::start().await;
+    serve_agent(&server).await;
+    Mock::given(method("GET"))
+        .and(path("/v1/convai/agents/agent_1/branches"))
+        .respond_with(
+            ResponseTemplate::new(200)
+                .set_body_json(json!({"results": [{"id": "agtbrch_1", "name": "staging"}]})),
+        )
+        .mount(&server)
+        .await;
+
+    let dir = tempfile::tempdir().unwrap();
+    let dir = dir.path();
+    ok(cli(dir, &server.uri(), &["agents", "init"]), "init");
+    std::fs::write(
+        dir.join("agents.json"),
+        r#"{"agents": [{"config": "agent_configs/support.yaml", "id": "agent_1",
+            "branches": {"staging": {"config": "agent_configs/support.staging.yaml",
+                                     "branch_id": "agtbrch_1"}}}]}"#,
+    )
+    .unwrap();
+    // Asked by ID this time, and for TOML: the registered YAML file still wins.
+    ok(
+        cli(
+            dir,
+            &server.uri(),
+            &[
+                "agents",
+                "pull",
+                "--all",
+                "--agent",
+                "agent_1",
+                "--branch",
+                "agtbrch_1",
+                "--config-format",
+                "toml",
+                "--yes",
+            ],
+        ),
+        "pull",
+    );
+
+    let index: Value =
+        serde_json::from_str(&std::fs::read_to_string(dir.join("agents.json")).unwrap()).unwrap();
+    let branches = index["agents"][0]["branches"].as_object().unwrap();
+    assert_eq!(branches.len(), 1, "{branches:?}");
+    assert_eq!(
+        branches["staging"]["config"],
+        "agent_configs/support.staging.yaml"
+    );
+    let text = std::fs::read_to_string(dir.join("agent_configs/support.staging.yaml")).unwrap();
+    let parsed: Value = serde_yaml::from_str(&text).unwrap();
+    assert_eq!(
+        parsed["conversation_config"],
+        live_agent()["conversation_config"]
+    );
+    let stray: Vec<_> = std::fs::read_dir(dir.join("agent_configs"))
+        .unwrap()
+        .map(|e| e.unwrap().file_name().into_string().unwrap())
+        .filter(|n| !n.starts_with("support."))
+        .collect();
+    assert!(stray.is_empty(), "{stray:?}");
+}
+
 #[tokio::test]
 async fn add_from_a_yaml_file_creates_a_yaml_config() {
     let server = MockServer::start().await;

From 2959c055f4b1e77a531ee871876ec4eb908592b4 Mon Sep 17 00:00:00 2001
From: Paul Asjes <paul.asjes@elevenlabs.io>
Date: Thu, 12 Nov 2026 14:30:08 +0100
Subject: [PATCH 3/5] fix: refuse nulls in objects inside mixed TOML arrays

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                                |  2 +-
 cli/elevenlabs/workflow/config_format.rs | 40 ++++++++++++++++--------
 2 files changed, 28 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 5b33c548..45f91adb 100644
--- a/README.md
+++ b/README.md
@@ -224,7 +224,7 @@ A config file's extension sets its format: `.json`, `.yaml`/`.yml` or `.toml`. T
 
 New files are JSON unless you pick another format. `agents pull --config-format toml` writes new agents as TOML, and a new branch file follows the format of its agent's config. Files that already exist keep their format. `agents add --from-file support.yaml` saves the agent's config as YAML too; `--config-format` overrides that.
 
-TOML has no `null`, so writing TOML drops null fields. For agents nothing is lost: `push` only changes the fields it sends, and a null field was unset already. What TOML can't do is clear a field, because deleting its line leaves the value on ElevenLabs unchanged. To clear one, set it to `null` in a JSON or YAML config. A `null` inside a list is data rather than an unset field, so a config with one can't be saved as TOML; the CLI says so and names the field.
+TOML has no `null`, so writing TOML drops null fields. For agents nothing is lost: `push` only changes the fields it sends, and a null field was unset already. What TOML can't do is clear a field, because deleting its line leaves the value on ElevenLabs unchanged. To clear one, set it to `null` in a JSON or YAML config. A `null` inside a list (an item, or a field of an object in a list of mixed values) is data rather than an unset field, so a config with one can't be saved as TOML; the CLI says so and names the field.
 
 ### Two surfaces in one namespace
 
diff --git a/cli/elevenlabs/workflow/config_format.rs b/cli/elevenlabs/workflow/config_format.rs
index 5368e46a..52aa3887 100644
--- a/cli/elevenlabs/workflow/config_format.rs
+++ b/cli/elevenlabs/workflow/config_format.rs
@@ -10,9 +10,10 @@
 //! loses nothing: `push` sends a PATCH, where a missing field is left as it
 //! is, and a field that pulled as null was unset already. What TOML can't
 //! express is *clearing* a field: deleting its line leaves the remote value
-//! alone. That needs `null` in a JSON or YAML config. A null array element is
-//! data rather than an unset field, so a config with one can't be written as
-//! TOML at all.
+//! alone. That needs `null` in a JSON or YAML config. A null anywhere inside
+//! an array that isn't a plain array of objects (an element, or a field of an
+//! object mixed in with other values) is data rather than an unset field, so
+//! a config with one can't be written as TOML at all.
 
 use std::path::Path;
 
@@ -125,11 +126,12 @@ fn join(path: &str, key: &str) -> String {
     }
 }
 
-/// A null in an array is data (a constant value, say), not an unset field:
-/// dropping it would change what `push` sends, so refuse instead.
+/// A null inside an inline array is data (a constant value, say), not an
+/// unset field: dropping it would change what `push` sends, so refuse
+/// instead. `path` is where the null is.
 fn null_in_array(path: &str) -> String {
     format!(
-        "{path} holds a null in an array, which TOML can't represent. \
+        "{path} is a null inside an array, which TOML can't represent. \
          Use a JSON or YAML config for this one"
     )
 }
@@ -163,7 +165,8 @@ fn to_item(value: &Value, path: &str) -> Result<Option<Item>, String> {
 }
 
 /// An inline TOML value: used for scalars, and for objects and arrays nested
-/// inside an array that isn't a plain array of objects.
+/// inside an array that isn't a plain array of objects. Any object reached
+/// here is inside such an array, so its null fields are refused too.
 fn to_value(value: &Value, path: &str) -> Result<Option<toml_edit::Value>, String> {
     Ok(Some(match value {
         Value::Null => return Ok(None),
@@ -178,9 +181,10 @@ fn to_value(value: &Value, path: &str) -> Result<Option<toml_edit::Value>, Strin
         Value::Array(items) => {
             let mut array = Array::new();
             for (i, item) in items.iter().enumerate() {
-                match to_value(item, &format!("{path}[{i}]"))? {
+                let item_path = format!("{path}[{i}]");
+                match to_value(item, &item_path)? {
                     Some(v) => array.push(v),
-                    None => return Err(null_in_array(path)),
+                    None => return Err(null_in_array(&item_path)),
                 }
             }
             array.into()
@@ -188,9 +192,11 @@ fn to_value(value: &Value, path: &str) -> Result<Option<toml_edit::Value>, Strin
         Value::Object(map) => {
             let mut table = InlineTable::new();
             for (key, item) in map {
-                if let Some(v) = to_value(item, &join(path, key))? {
-                    table.insert(key, v);
-                }
+                let item_path = join(path, key);
+                match to_value(item, &item_path)? {
+                    Some(v) => table.insert(key, v),
+                    None => return Err(null_in_array(&item_path)),
+                };
             }
             table.into()
         }
@@ -360,6 +366,9 @@ mod tests {
             json!({"tool": {"constant_value": [1, null, 2]}}),
             json!({"tables": [{"a": 1}, null]}),
             json!({"nested": [[null]]}),
+            // An object mixed in with other values is literal data too.
+            json!({"mixed": [1, {"a": null}]}),
+            json!({"nested": [[{"a": {"b": null}}]]}),
         ] {
             let err = ConfigFormat::Toml.render(&value).unwrap_err().to_string();
             assert!(err.contains("Use a JSON or YAML config"), "{err}");
@@ -368,7 +377,12 @@ mod tests {
             .render(&json!({"tool": {"constant_value": [1, null]}}))
             .unwrap_err()
             .to_string();
-        assert!(err.starts_with("tool.constant_value holds a null"), "{err}");
+        assert!(err.starts_with("tool.constant_value[1] is a null"), "{err}");
+        let err = ConfigFormat::Toml
+            .render(&json!({"mixed": [1, {"a": null}]}))
+            .unwrap_err()
+            .to_string();
+        assert!(err.starts_with("mixed[1].a is a null"), "{err}");
     }
 
     #[test]

From 1ac43bfcdadb7ab4d4ec4b860a5bb2e486401849 Mon Sep 17 00:00:00 2001
From: Paul Asjes <paul.asjes@elevenlabs.io>
Date: Thu, 12 Nov 2026 14:42:43 +0100
Subject: [PATCH 4/5] fix: refuse .nan and .inf in YAML configs instead of
 reading them as null

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 cli/elevenlabs/workflow/config_format.rs | 55 +++++++++++++++++++++++-
 1 file changed, 54 insertions(+), 1 deletion(-)

diff --git a/cli/elevenlabs/workflow/config_format.rs b/cli/elevenlabs/workflow/config_format.rs
index 52aa3887..f9410c26 100644
--- a/cli/elevenlabs/workflow/config_format.rs
+++ b/cli/elevenlabs/workflow/config_format.rs
@@ -77,7 +77,12 @@ impl ConfigFormat {
     pub fn parse(self, text: &str) -> Result<Value, String> {
         match self {
             Self::Json => serde_json::from_str(text).map_err(|e| e.to_string()),
-            Self::Yaml => serde_yaml::from_str(text).map_err(|e| e.to_string()),
+            Self::Yaml => {
+                let yaml: serde_yaml::Value =
+                    serde_yaml::from_str(text).map_err(|e| e.to_string())?;
+                check_yaml_numbers(&yaml, "")?;
+                serde_yaml::from_value(yaml).map_err(|e| e.to_string())
+            }
             Self::Toml => {
                 let doc: DocumentMut = text.parse().map_err(|e| format!("{e}"))?;
                 table_to_json(doc.as_table())
@@ -97,6 +102,35 @@ impl ConfigFormat {
     }
 }
 
+// ── YAML → JSON ─────────────────────────────────────────────────────
+
+/// YAML's `.nan` and `.inf` would quietly become `null` in JSON, which
+/// `push` then sends as a cleared field. Refuse them, as the TOML reader does.
+fn check_yaml_numbers(value: &serde_yaml::Value, path: &str) -> Result<(), String> {
+    use serde_yaml::Value as Y;
+    match value {
+        Y::Number(n) if n.is_nan() || n.is_infinite() => {
+            let at = if path.is_empty() { "value" } else { path };
+            Err(format!("{at}: {n} has no JSON equivalent"))
+        }
+        Y::Sequence(items) => items
+            .iter()
+            .enumerate()
+            .try_for_each(|(i, item)| check_yaml_numbers(item, &format!("{path}[{i}]"))),
+        Y::Mapping(map) => map.iter().try_for_each(|(key, item)| {
+            let key = match key {
+                Y::String(s) => s.clone(),
+                other => serde_yaml::to_string(other)
+                    .map(|s| s.trim_end().to_string())
+                    .unwrap_or_default(),
+            };
+            check_yaml_numbers(item, &join(path, &key))
+        }),
+        Y::Tagged(tagged) => check_yaml_numbers(&tagged.value, path),
+        _ => Ok(()),
+    }
+}
+
 // ── JSON → TOML ─────────────────────────────────────────────────────
 
 fn json_to_toml(value: &Value) -> Result<String, String> {
@@ -396,6 +430,25 @@ mod tests {
         assert!(ConfigFormat::Toml.parse("x = nan").is_err());
     }
 
+    #[test]
+    fn yaml_rejects_non_finite_numbers() {
+        // These would otherwise read as null and clear the field on push.
+        for text in ["temperature: .nan", "a:\n  b: [1, .inf]", "x: -.inf"] {
+            assert!(
+                ConfigFormat::Yaml.parse(text).is_err(),
+                "{text} should be refused"
+            );
+        }
+        let err = ConfigFormat::Yaml
+            .parse("tts:\n  stability: .nan")
+            .unwrap_err();
+        assert!(err.starts_with("tts.stability:"), "{err}");
+        assert_eq!(
+            ConfigFormat::Yaml.parse("t: 0.5").unwrap(),
+            json!({"t": 0.5})
+        );
+    }
+
     #[test]
     fn toml_datetimes_read_as_strings() {
         assert_eq!(

From bb2d57bc0c6cb5e3918e2de2631b2ac7ae69499a Mon Sep 17 00:00:00 2001
From: Paul Asjes <paul.asjes@elevenlabs.io>
Date: Thu, 12 Nov 2026 15:04:45 +0100
Subject: [PATCH 5/5] fix: refuse nulls in free-form TOML values, keep pulling
 past unwritable configs

A null inside constant_value, dynamic variables or a tool's schemas is part
of the value, so writing TOML now refuses it instead of dropping it. A pull
that can't write one config reports it, still writes and registers the
rest, and exits with an error.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                                |  2 +-
 cli/elevenlabs/workflow/agents.rs        | 54 ++++++++++++----
 cli/elevenlabs/workflow/config_format.rs | 81 ++++++++++++++++++------
 cli/elevenlabs/workflow/tests.rs         | 19 +++++-
 cli/elevenlabs/workflow/tools.rs         | 19 +++++-
 tests/agents_config_format_test.rs       | 58 +++++++++++++++++
 6 files changed, 198 insertions(+), 35 deletions(-)

diff --git a/README.md b/README.md
index 45f91adb..4734545f 100644
--- a/README.md
+++ b/README.md
@@ -224,7 +224,7 @@ A config file's extension sets its format: `.json`, `.yaml`/`.yml` or `.toml`. T
 
 New files are JSON unless you pick another format. `agents pull --config-format toml` writes new agents as TOML, and a new branch file follows the format of its agent's config. Files that already exist keep their format. `agents add --from-file support.yaml` saves the agent's config as YAML too; `--config-format` overrides that.
 
-TOML has no `null`, so writing TOML drops null fields. For agents nothing is lost: `push` only changes the fields it sends, and a null field was unset already. What TOML can't do is clear a field, because deleting its line leaves the value on ElevenLabs unchanged. To clear one, set it to `null` in a JSON or YAML config. A `null` inside a list (an item, or a field of an object in a list of mixed values) is data rather than an unset field, so a config with one can't be saved as TOML; the CLI says so and names the field.
+TOML has no `null`, so writing TOML drops null fields. For agents nothing is lost: `push` only changes the fields it sends, and a null field was unset already. What TOML can't do is clear a field, because deleting its line leaves the value on ElevenLabs unchanged. To clear one, set it to `null` in a JSON or YAML config. Some nulls are data rather than unset fields: one inside a list (an item, or a field of an object in a list of mixed values), or anywhere within a free-form value such as a tool parameter's `constant_value`. A config with one of those can't be saved as TOML; the CLI says so and names the field.
 
 ### Two surfaces in one namespace
 
diff --git a/cli/elevenlabs/workflow/agents.rs b/cli/elevenlabs/workflow/agents.rs
index 15bfc991..a419e74b 100644
--- a/cli/elevenlabs/workflow/agents.rs
+++ b/cli/elevenlabs/workflow/agents.rs
@@ -1046,6 +1046,9 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
     }
 
     let mut processed = 0;
+    // Configs that couldn't be written (TOML can't hold some values). The
+    // rest are still registered, so a retry doesn't duplicate their files.
+    let mut failed = 0;
     for (action, id, name, existing_idx) in &plan {
         if *action == PullAction::Skip {
             println!("⊘ Skipping '{name}' (already exists, use --update to overwrite)");
@@ -1088,7 +1091,11 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
         let entry_idx = match existing_idx {
             Some(i) => {
                 let cfg_path = registry.agents[*i].config.clone();
-                project::write_config_in_project(&cfg_path, &config)?;
+                if let Err(e) = project::write_config_in_project(&cfg_path, &config) {
+                    println!("  ✗ Error saving '{name}': {e}");
+                    failed += 1;
+                    continue;
+                }
                 if let Some(v) = &version_id {
                     registry.agents[*i].version_id = Some(v.clone());
                 }
@@ -1103,7 +1110,11 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
                 let cfg_path = project::generate_unique_filename(&output_dir, name, ext)
                     .display()
                     .to_string();
-                project::write_config_in_project(&cfg_path, &config)?;
+                if let Err(e) = project::write_config_in_project(&cfg_path, &config) {
+                    println!("  ✗ Error saving '{name}': {e}");
+                    failed += 1;
+                    continue;
+                }
                 registry.agents.push(project::AgentDefinition {
                     config: cfg_path.clone(),
                     id: Some(id.clone()),
@@ -1115,6 +1126,7 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
                 registry.agents.len() - 1
             }
         };
+        processed += 1;
 
         // --branch: persist the branch config alongside the main one.
         if let (Some(branch), Some(bid)) = (&branch, &branch_id) {
@@ -1139,7 +1151,11 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
                     .to_string(),
                 ),
             };
-            project::write_config_in_project(&branch_path, &config)?;
+            if let Err(e) = project::write_config_in_project(&branch_path, &config) {
+                println!("  ✗ Error saving branch '{branch}' of '{name}': {e}");
+                failed += 1;
+                continue;
+            }
             let branches = registry.agents[entry_idx]
                 .branches
                 .get_or_insert_with(Default::default);
@@ -1155,7 +1171,7 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
         }
 
         if all_branches {
-            pull_all_branches(
+            match pull_all_branches(
                 ctx,
                 id,
                 name,
@@ -1163,10 +1179,14 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
                 &mut registry,
                 &output_dir,
                 config_format,
-            )?;
+            ) {
+                Ok(n) => failed += n,
+                Err(e) => {
+                    println!("  ✗ Error pulling branches of '{name}': {e}");
+                    failed += 1;
+                }
+            }
         }
-
-        processed += 1;
     }
 
     if !dry_run && processed > 0 {
@@ -1185,6 +1205,11 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
             );
         }
     }
+    if failed > 0 {
+        return Err(CliError::Validation(format!(
+            "{failed} config(s) could not be saved; see the errors above"
+        )));
+    }
     Ok(())
 }
 
@@ -1199,6 +1224,7 @@ fn new_config_ext(flag: Option<ConfigFormat>, agent_config: Option<&str>) -> &'s
 
 /// Pull every non-archived, non-main branch for an agent into config files
 /// tracked under its `agents.json` entry. Ports v0's `pullAllBranches`.
+/// Returns how many branch configs couldn't be written.
 fn pull_all_branches(
     ctx: &AppContext,
     agent_id: &str,
@@ -1207,14 +1233,16 @@ fn pull_all_branches(
     registry: &mut project::AgentsConfig,
     output_dir: &str,
     config_format: Option<ConfigFormat>,
-) -> Result<(), CliError> {
+) -> Result<usize, CliError> {
     println!("  Fetching branches for '{agent_name}'...");
     let branches = api::list_branches(ctx, agent_id, false)?;
     if branches.is_empty() {
         println!("  No branches found for '{agent_name}'");
-        return Ok(());
+        return Ok(0);
     }
 
+    let mut failed = 0;
+
     let parent_branch_id = registry.agents[entry_idx].branch_id.clone();
     for branch in &branches {
         if branch
@@ -1258,7 +1286,11 @@ fn pull_all_branches(
                 .display()
                 .to_string()
         });
-        project::write_config_in_project(&branch_path, &branch_config)?;
+        if let Err(e) = project::write_config_in_project(&branch_path, &branch_config) {
+            println!("  ✗ Error saving branch '{bname}': {e}");
+            failed += 1;
+            continue;
+        }
 
         let map = registry.agents[entry_idx]
             .branches
@@ -1282,7 +1314,7 @@ fn pull_all_branches(
     if count > 0 {
         println!("  {count} branch(es) stored");
     }
-    Ok(())
+    Ok(failed)
 }
 
 /// Extract the on-disk config (name + conversation_config + platform_settings
diff --git a/cli/elevenlabs/workflow/config_format.rs b/cli/elevenlabs/workflow/config_format.rs
index f9410c26..87e6942a 100644
--- a/cli/elevenlabs/workflow/config_format.rs
+++ b/cli/elevenlabs/workflow/config_format.rs
@@ -10,10 +10,12 @@
 //! loses nothing: `push` sends a PATCH, where a missing field is left as it
 //! is, and a field that pulled as null was unset already. What TOML can't
 //! express is *clearing* a field: deleting its line leaves the remote value
-//! alone. That needs `null` in a JSON or YAML config. A null anywhere inside
-//! an array that isn't a plain array of objects (an element, or a field of an
-//! object mixed in with other values) is data rather than an unset field, so
-//! a config with one can't be written as TOML at all.
+//! alone. That needs `null` in a JSON or YAML config.
+//!
+//! Some nulls are data rather than unset fields, and a config holding one
+//! can't be written as TOML at all: any null inside an array that isn't a
+//! plain array of objects, and any null within a free-form JSON value such as
+//! a tool parameter's `constant_value` (see [`LITERAL_KEYS`]).
 
 use std::path::Path;
 
@@ -138,15 +140,39 @@ fn json_to_toml(value: &Value) -> Result<String, String> {
         return Err("A TOML config must be an object at the top level".to_string());
     };
     let mut doc = DocumentMut::new();
-    fill_table(doc.as_table_mut(), map, "")?;
+    fill_table(doc.as_table_mut(), map, "", false)?;
     Ok(doc.to_string())
 }
 
-/// `path` is the dotted key path of `map`, for error messages.
-fn fill_table(table: &mut Table, map: &Map<String, Value>, path: &str) -> Result<(), String> {
+/// API fields whose value is free-form JSON sent through as it is, so a
+/// null inside one is part of the value. The field itself being null still
+/// just means it's unset.
+const LITERAL_KEYS: [&str; 5] = [
+    "constant_value",
+    "dynamic_variable_placeholders",
+    "dynamic_variables",
+    "input_schema",
+    "output_schema",
+];
+
+/// `path` is the dotted key path of `map`, for error messages. `literal` is
+/// set within a [`LITERAL_KEYS`] value, where a null field is refused rather
+/// than dropped.
+fn fill_table(
+    table: &mut Table,
+    map: &Map<String, Value>,
+    path: &str,
+    literal: bool,
+) -> Result<(), String> {
     for (key, value) in map {
-        if let Some(item) = to_item(value, &join(path, key))? {
-            table.insert(key, item);
+        let item_path = join(path, key);
+        let literal_child = literal || LITERAL_KEYS.contains(&key.as_str());
+        match to_item(value, &item_path, literal_child)? {
+            Some(item) => {
+                table.insert(key, item);
+            }
+            None if literal => return Err(literal_null(&item_path)),
+            None => {}
         }
     }
     Ok(())
@@ -160,12 +186,13 @@ fn join(path: &str, key: &str) -> String {
     }
 }
 
-/// A null inside an inline array is data (a constant value, say), not an
+/// A null that is data (in an array, or within a constant value), not an
 /// unset field: dropping it would change what `push` sends, so refuse
 /// instead. `path` is where the null is.
-fn null_in_array(path: &str) -> String {
+fn literal_null(path: &str) -> String {
     format!(
-        "{path} is a null inside an array, which TOML can't represent. \
+        "{path} is null, which TOML can't represent: inside an array or a \
+         free-form value like constant_value, a null is data. \
          Use a JSON or YAML config for this one"
     )
 }
@@ -173,11 +200,11 @@ fn null_in_array(path: &str) -> String {
 /// Objects become `[table]` sections and arrays of objects `[[array]]`
 /// sections, which keeps a deeply nested agent config readable. `None` for
 /// a null field, which TOML can't hold.
-fn to_item(value: &Value, path: &str) -> Result<Option<Item>, String> {
+fn to_item(value: &Value, path: &str, literal: bool) -> Result<Option<Item>, String> {
     match value {
         Value::Object(map) => {
             let mut table = Table::new();
-            fill_table(&mut table, map, path)?;
+            fill_table(&mut table, map, path, literal)?;
             // An implicit table prints no header of its own when it holds
             // only subtables. An empty one must keep its header, or the
             // (empty) object would vanish from the file. Checked after
@@ -189,7 +216,7 @@ fn to_item(value: &Value, path: &str) -> Result<Option<Item>, String> {
             let mut tables = ArrayOfTables::new();
             for (i, map) in items.iter().filter_map(Value::as_object).enumerate() {
                 let mut table = Table::new();
-                fill_table(&mut table, map, &format!("{path}[{i}]"))?;
+                fill_table(&mut table, map, &format!("{path}[{i}]"), literal)?;
                 tables.push(table);
             }
             Ok(Some(Item::ArrayOfTables(tables)))
@@ -218,7 +245,7 @@ fn to_value(value: &Value, path: &str) -> Result<Option<toml_edit::Value>, Strin
                 let item_path = format!("{path}[{i}]");
                 match to_value(item, &item_path)? {
                     Some(v) => array.push(v),
-                    None => return Err(null_in_array(&item_path)),
+                    None => return Err(literal_null(&item_path)),
                 }
             }
             array.into()
@@ -229,7 +256,7 @@ fn to_value(value: &Value, path: &str) -> Result<Option<toml_edit::Value>, Strin
                 let item_path = join(path, key);
                 match to_value(item, &item_path)? {
                     Some(v) => table.insert(key, v),
-                    None => return Err(null_in_array(&item_path)),
+                    None => return Err(literal_null(&item_path)),
                 };
             }
             table.into()
@@ -403,6 +430,10 @@ mod tests {
             // An object mixed in with other values is literal data too.
             json!({"mixed": [1, {"a": null}]}),
             json!({"nested": [[{"a": {"b": null}}]]}),
+            // So is anything within a free-form value, even a list of objects.
+            json!({"tool": {"constant_value": {"key": null}}}),
+            json!({"tool": {"constant_value": [{"key": null}]}}),
+            json!({"dynamic_variables": {"user": null}}),
         ] {
             let err = ConfigFormat::Toml.render(&value).unwrap_err().to_string();
             assert!(err.contains("Use a JSON or YAML config"), "{err}");
@@ -411,12 +442,24 @@ mod tests {
             .render(&json!({"tool": {"constant_value": [1, null]}}))
             .unwrap_err()
             .to_string();
-        assert!(err.starts_with("tool.constant_value[1] is a null"), "{err}");
+        assert!(err.starts_with("tool.constant_value[1] is null"), "{err}");
         let err = ConfigFormat::Toml
             .render(&json!({"mixed": [1, {"a": null}]}))
             .unwrap_err()
             .to_string();
-        assert!(err.starts_with("mixed[1].a is a null"), "{err}");
+        assert!(err.starts_with("mixed[1].a is null"), "{err}");
+        let err = ConfigFormat::Toml
+            .render(&json!({"tool": {"constant_value": {"key": null}}}))
+            .unwrap_err()
+            .to_string();
+        assert!(err.starts_with("tool.constant_value.key is null"), "{err}");
+        // A free-form field that is null itself is just unset.
+        assert_eq!(
+            ConfigFormat::Toml
+                .render(&json!({"tool": {"constant_value": null, "a": 1}}))
+                .unwrap(),
+            "[tool]\na = 1\n"
+        );
     }
 
     #[test]
diff --git a/cli/elevenlabs/workflow/tests.rs b/cli/elevenlabs/workflow/tests.rs
index 9b474540..012c44f3 100644
--- a/cli/elevenlabs/workflow/tests.rs
+++ b/cli/elevenlabs/workflow/tests.rs
@@ -685,6 +685,8 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
     }
 
     let mut processed = 0;
+    // Configs that couldn't be written; the rest are still registered.
+    let mut failed = 0;
     for (action, id, name, existing_idx) in &plan {
         if *action == PullAction::Skip {
             println!("⊘ Skipping '{name}' (already exists, use --update to overwrite)");
@@ -719,14 +721,22 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
         match existing_idx {
             Some(i) => {
                 let cfg_path = registry.tests[*i].config.clone();
-                project::write_config_in_project(&cfg_path, &config)?;
+                if let Err(e) = project::write_config_in_project(&cfg_path, &config) {
+                    println!("  ✗ Error saving '{name}': {e}");
+                    failed += 1;
+                    continue;
+                }
                 println!("  ✓ Updated '{name}' (config: {cfg_path})");
             }
             None => {
                 let cfg_path = project::generate_unique_filename(&output_dir, name, ".json")
                     .display()
                     .to_string();
-                project::write_config_in_project(&cfg_path, &config)?;
+                if let Err(e) = project::write_config_in_project(&cfg_path, &config) {
+                    println!("  ✗ Error saving '{name}': {e}");
+                    failed += 1;
+                    continue;
+                }
                 registry.tests.push(project::TestDefinition {
                     config: cfg_path.clone(),
                     test_type,
@@ -753,6 +763,11 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
             );
         }
     }
+    if failed > 0 {
+        return Err(CliError::Validation(format!(
+            "{failed} test config(s) could not be saved; see the errors above"
+        )));
+    }
     Ok(())
 }
 
diff --git a/cli/elevenlabs/workflow/tools.rs b/cli/elevenlabs/workflow/tools.rs
index 3c5c698b..66867e89 100644
--- a/cli/elevenlabs/workflow/tools.rs
+++ b/cli/elevenlabs/workflow/tools.rs
@@ -519,6 +519,8 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
     }
 
     let mut processed = 0;
+    // Configs that couldn't be written; the rest are still registered.
+    let mut failed = 0;
     for (action, id, name, existing_idx) in &plan {
         if *action == PullAction::Skip {
             println!("⊘ Skipping '{name}' (already exists, use --update to overwrite)");
@@ -561,14 +563,22 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
         match existing_idx {
             Some(i) => {
                 let cfg_path = registry.tools[*i].config.clone();
-                project::write_config_in_project(&cfg_path, &tool_config)?;
+                if let Err(e) = project::write_config_in_project(&cfg_path, &tool_config) {
+                    println!("  ✗ Error saving '{name}': {e}");
+                    failed += 1;
+                    continue;
+                }
                 println!("  ✓ Updated '{name}' (config: {cfg_path})");
             }
             None => {
                 let cfg_path = project::generate_unique_filename(&output_dir, name, ".json")
                     .display()
                     .to_string();
-                project::write_config_in_project(&cfg_path, &tool_config)?;
+                if let Err(e) = project::write_config_in_project(&cfg_path, &tool_config) {
+                    println!("  ✗ Error saving '{name}': {e}");
+                    failed += 1;
+                    continue;
+                }
                 registry.tools.push(project::ToolDefinition {
                     tool_type: tool_type.clone(),
                     config: cfg_path.clone(),
@@ -595,6 +605,11 @@ fn handle_pull(matches: &clap::ArgMatches, ctx: &AppContext) -> Result<(), CliEr
             );
         }
     }
+    if failed > 0 {
+        return Err(CliError::Validation(format!(
+            "{failed} tool config(s) could not be saved; see the errors above"
+        )));
+    }
     Ok(())
 }
 
diff --git a/tests/agents_config_format_test.rs b/tests/agents_config_format_test.rs
index 8794e486..50331b0c 100644
--- a/tests/agents_config_format_test.rs
+++ b/tests/agents_config_format_test.rs
@@ -312,3 +312,61 @@ fn a_bad_toml_config_names_the_format() {
         "{text}"
     );
 }
+
+#[tokio::test]
+async fn a_config_toml_cannot_hold_does_not_lose_the_others() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/v1/convai/agents"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+            "agents": [
+                {"agent_id": "agent_1", "name": "Support"},
+                {"agent_id": "agent_2", "name": "Sales"}
+            ],
+            "has_more": false
+        })))
+        .mount(&server)
+        .await;
+    serve_agent(&server).await;
+    let mut sales = live_agent();
+    sales["agent_id"] = json!("agent_2");
+    sales["name"] = json!("Sales");
+    sales["tags"] = json!(["a", null]);
+    Mock::given(method("GET"))
+        .and(path("/v1/convai/agents/agent_2"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(sales))
+        .mount(&server)
+        .await;
+
+    let dir = tempfile::tempdir().unwrap();
+    let dir = dir.path();
+    ok(cli(dir, &server.uri(), &["agents", "init"]), "init");
+    let out = cli(
+        dir,
+        &server.uri(),
+        &[
+            "agents",
+            "pull",
+            "--all",
+            "--config-format",
+            "toml",
+            "--yes",
+        ],
+    );
+    let text = format!(
+        "{}{}",
+        String::from_utf8_lossy(&out.stdout),
+        String::from_utf8_lossy(&out.stderr)
+    );
+    assert!(!out.status.success(), "{text}");
+    assert!(text.contains("tags[1] is null"), "{text}");
+
+    // Support was still written and registered, so a retry updates it
+    // rather than writing a second copy.
+    let index: Value =
+        serde_json::from_str(&std::fs::read_to_string(dir.join("agents.json")).unwrap()).unwrap();
+    let agents = index["agents"].as_array().unwrap();
+    assert_eq!(agents.len(), 1, "{agents:?}");
+    assert_eq!(agents[0]["id"], "agent_1");
+    assert!(dir.join(agents[0]["config"].as_str().unwrap()).exists());
+}