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..4734545f 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. 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
 
 `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..a419e74b 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");
@@ -1009,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)");
@@ -1051,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_json_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());
                 }
@@ -1062,10 +1106,15 @@ 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)?;
+                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()),
@@ -1077,22 +1126,41 @@ 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) {
-            let branch_path = project::generate_unique_filename(
-                &output_dir,
-                &format!("{name}.{branch}"),
-                ".json",
-            )
-            .display()
-            .to_string();
-            project::write_json_in_project(&branch_path, &config)?;
+            // 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(),
+                ),
+            };
+            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);
             branches.insert(
-                branch.clone(),
+                branch_key,
                 project::BranchDefinition {
                     config: branch_path.clone(),
                     branch_id: bid.clone(),
@@ -1103,10 +1171,22 @@ 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)?;
+            match pull_all_branches(
+                ctx,
+                id,
+                name,
+                entry_idx,
+                &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 {
@@ -1125,11 +1205,26 @@ 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(())
 }
 
+/// 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`.
+/// Returns how many branch configs couldn't be written.
 fn pull_all_branches(
     ctx: &AppContext,
     agent_id: &str,
@@ -1137,14 +1232,17 @@ fn pull_all_branches(
     entry_idx: usize,
     registry: &mut project::AgentsConfig,
     output_dir: &str,
-) -> Result<(), CliError> {
+    config_format: Option<ConfigFormat>,
+) -> 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
@@ -1183,11 +1281,16 @@ 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)?;
+        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
@@ -1211,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
new file mode 100644
index 00000000..87e6942a
--- /dev/null
+++ b/cli/elevenlabs/workflow/config_format.rs
@@ -0,0 +1,511 @@
+//! 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. 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.
+//!
+//! 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;
+
+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 => {
+                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())
+            }
+        }
+    }
+
+    /// 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),
+        }
+    }
+}
+
+// ── 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> {
+    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, "", false)?;
+    Ok(doc.to_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 {
+        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(())
+}
+
+fn join(path: &str, key: &str) -> String {
+    if path.is_empty() {
+        key.to_string()
+    } else {
+        format!("{path}.{key}")
+    }
+}
+
+/// 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 literal_null(path: &str) -> String {
+    format!(
+        "{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"
+    )
+}
+
+/// 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, literal: bool) -> Result<Option<Item>, String> {
+    match value {
+        Value::Object(map) => {
+            let mut table = Table::new();
+            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
+            // 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.is_empty() && items.iter().all(Value::is_object) => {
+            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}]"), literal)?;
+                tables.push(table);
+            }
+            Ok(Some(Item::ArrayOfTables(tables)))
+        }
+        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. 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),
+        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!("{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 (i, item) in items.iter().enumerate() {
+                let item_path = format!("{path}[{i}]");
+                match to_value(item, &item_path)? {
+                    Some(v) => array.push(v),
+                    None => return Err(literal_null(&item_path)),
+                }
+            }
+            array.into()
+        }
+        Value::Object(map) => {
+            let mut table = InlineTable::new();
+            for (key, item) in map {
+                let item_path = join(path, key);
+                match to_value(item, &item_path)? {
+                    Some(v) => table.insert(key, v),
+                    None => return Err(literal_null(&item_path)),
+                };
+            }
+            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_null_fields() {
+        let value = json!({
+            "name": "x",
+            "language": null,
+            "nested": {"keep": 1, "drop": null},
+            "only_nulls": {"drop": null},
+            "tables": [{"a": 1, "b": null}]
+        });
+        let rendered = ConfigFormat::Toml.render(&value).unwrap();
+        assert_eq!(
+            ConfigFormat::Toml.parse(&rendered).unwrap(),
+            json!({
+                "name": "x",
+                "nested": {"keep": 1},
+                // 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]]}),
+            // 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}");
+        }
+        let err = ConfigFormat::Toml
+            .render(&json!({"tool": {"constant_value": [1, null]}}))
+            .unwrap_err()
+            .to_string();
+        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 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]
+    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 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!(
+            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..012c44f3 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
@@ -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_json_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_json_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 a87c4d79..66867e89 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 {
@@ -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_json_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_json_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
new file mode 100644
index 00000000..50331b0c
--- /dev/null
+++ b/tests/agents_config_format_test.rs
@@ -0,0 +1,372 @@
+//! 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 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;
+    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}"
+    );
+}
+
+#[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());
+}