feat(cli): add --config option to specify custom truss config path

Add support for specifying a custom config file path via the --config
option in the push and watch commands. This allows users to use
alternative config files instead of the default config.yaml.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: armishra

truss/base/truss_spec.py

@@ -14,19 +14,25 @@ class TrussSpec:
     Helper class for easy access to information in a Truss.
     """
 
-    def __init__(self, truss_dir: Path) -> None:
+    def __init__(self, truss_dir: Path, config_path: Optional[Path] = None) -> None:
         self._truss_dir = truss_dir
-        self._config = truss_config.TrussConfig.from_yaml(
-            truss_dir / constants.CONFIG_FILE
-        )
+        self._config_path = self._resolve_config_path(truss_dir, config_path)
+        self._config = truss_config.TrussConfig.from_yaml(self._config_path)
+
+    @staticmethod
+    def _resolve_config_path(truss_dir: Path, config_path: Optional[Path]) -> Path:
+        """Return custom config path if provided, otherwise default to config.yaml."""
+        if config_path:
+            return config_path
+        return truss_dir / constants.CONFIG_FILE
 
     @property
     def truss_dir(self) -> Path:
         return self._truss_dir
 
     @property
     def config_path(self) -> Path:
-        return self._truss_dir / constants.CONFIG_FILE
+        return self._config_path
 
     @property
     def data_dir(self) -> Path:

truss/cli/cli.py

@@ -73,17 +73,20 @@
 }
 
 
-def _get_truss_from_directory(target_directory: Optional[str] = None):
+def _get_truss_from_directory(
+    target_directory: Optional[str] = None, config: Optional[str] = None
+):
     """Gets Truss from directory. If none, use the current directory"""
     if target_directory is None:
         target_directory = os.getcwd()
+    config_path = Path(config) if config else None
     if not os.path.isfile(target_directory):
-        return load(target_directory)
+        return load(target_directory, config_path=config_path)
     # These imports are delayed, to handle pydantic v1 envs gracefully.
     from truss_chains.deployment import code_gen
 
     truss_dir = code_gen.gen_truss_model_from_source(Path(target_directory))
-    return load(truss_dir)
+    return load(truss_dir, config_path=config_path)
 
 
 ### Top-level & utility commands. ######################################################
@@ -408,6 +411,12 @@ def run_python(script, target_directory):
 
 @truss_cli.command()
 @click.argument("target_directory", required=False, default=os.getcwd())
+@click.option(
+    "--config",
+    type=click.Path(exists=True),
+    required=False,
+    help="Path to a custom config file (default: config.yaml in truss directory)",
+)
 @click.option(
     "--remote",
     type=str,
@@ -532,6 +541,7 @@ def run_python(script, target_directory):
 @common.common_options()
 def push(
     target_directory: str,
+    config: Optional[str],
     remote: str,
     model_name: str,
     publish: bool = False,
@@ -555,7 +565,7 @@ def push(
     TARGET_DIRECTORY: A Truss directory. If none, use current directory.
 
     """
-    tr = _get_truss_from_directory(target_directory=target_directory)
+    tr = _get_truss_from_directory(target_directory=target_directory, config=config)
 
     if tr.spec.config.resources.instance_type:
         console.print(
@@ -777,6 +787,12 @@ def model_logs(
 
 @truss_cli.command()
 @click.argument("target_directory", required=False, default=os.getcwd())
+@click.option(
+    "--config",
+    type=click.Path(exists=True),
+    required=False,
+    help="Path to a custom config file (default: config.yaml in truss directory)",
+)
 @click.option(
     "--remote",
     type=str,
@@ -792,7 +808,10 @@ def model_logs(
 )
 @common.common_options()
 def watch(
-    target_directory: str, remote: str, provided_team_name: Optional[str] = None
+    target_directory: str,
+    config: Optional[str],
+    remote: str,
+    provided_team_name: Optional[str] = None,
 ) -> None:
     """
     Seamless remote development with truss
@@ -805,7 +824,7 @@ def watch(
 
     remote_provider = cast(BasetenRemote, RemoteFactory.create(remote=remote))
 
-    tr = _get_truss_from_directory(target_directory=target_directory)
+    tr = _get_truss_from_directory(target_directory=target_directory, config=config)
     model_name = tr.spec.config.model_name
     if not model_name:
         console.print(

truss/tests/test_custom_config_path.py

@@ -0,0 +1,158 @@
+"""Tests for custom config path functionality.
+
+This module tests the --config option that allows specifying a custom config file
+instead of the default config.yaml in the truss directory.
+"""
+
+import shutil
+import tempfile
+from pathlib import Path
+
+import pytest
+import yaml
+
+from truss.base.truss_spec import TrussSpec
+from truss.truss_handle.build import load
+from truss.truss_handle.truss_handle import TrussHandle
+
+
+@pytest.fixture
+def truss_dir_with_multiple_configs(test_data_path: Path):
+    """Create a truss directory with multiple config files for testing."""
+    source_dir = test_data_path / "test_basic_truss"
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        tmp_path = Path(tmp_dir)
+        truss_path = tmp_path / "test_truss"
+        shutil.copytree(source_dir, truss_path)
+
+        # Read the original config
+        original_config_path = truss_path / "config.yaml"
+        with open(original_config_path) as f:
+            original_config = yaml.safe_load(f)
+
+        # Create an alternate config with different model_name
+        alt_config = original_config.copy()
+        alt_config["model_name"] = "alternate-model"
+        alt_config_path = truss_path / "config.dev.yaml"
+        with open(alt_config_path, "w") as f:
+            yaml.dump(alt_config, f)
+
+        # Create another alternate config outside the truss directory
+        external_config = original_config.copy()
+        external_config["model_name"] = "external-model"
+        external_config_path = tmp_path / "external_config.yaml"
+        with open(external_config_path, "w") as f:
+            yaml.dump(external_config, f)
+
+        yield {
+            "truss_dir": truss_path,
+            "default_config": original_config_path,
+            "alt_config": alt_config_path,
+            "external_config": external_config_path,
+            "original_model_name": original_config.get("model_name"),
+        }
+
+
+class TestTrussSpecCustomConfigPath:
+    """Tests for TrussSpec with custom config path."""
+
+    def test_default_config_path_backwards_compatibility(
+        self, truss_dir_with_multiple_configs
+    ):
+        """Test that TrussSpec without config_path uses default config.yaml."""
+        data = truss_dir_with_multiple_configs
+        spec = TrussSpec(data["truss_dir"])
+
+        # Should load from default config.yaml
+        assert spec.config_path == data["default_config"]
+        assert spec.config.model_name == data["original_model_name"]
+
+    def test_custom_config_path_in_truss_dir(self, truss_dir_with_multiple_configs):
+        """Test that TrussSpec with config_path loads from that file."""
+        data = truss_dir_with_multiple_configs
+        spec = TrussSpec(data["truss_dir"], config_path=data["alt_config"])
+
+        # Should load from alternate config
+        assert spec.config_path == data["alt_config"]
+        assert spec.config.model_name == "alternate-model"
+
+    def test_custom_config_path_external(self, truss_dir_with_multiple_configs):
+        """Test that TrussSpec with external config_path works."""
+        data = truss_dir_with_multiple_configs
+        spec = TrussSpec(data["truss_dir"], config_path=data["external_config"])
+
+        # Should load from external config
+        assert spec.config_path == data["external_config"]
+        assert spec.config.model_name == "external-model"
+
+
+class TestTrussHandleCustomConfigPath:
+    """Tests for TrussHandle with custom config path."""
+
+    def test_default_config_path_backwards_compatibility(
+        self, truss_dir_with_multiple_configs
+    ):
+        """Test that TrussHandle without config_path uses default config.yaml."""
+        data = truss_dir_with_multiple_configs
+        handle = TrussHandle(data["truss_dir"])
+
+        # Should load from default config.yaml
+        assert handle.spec.config_path == data["default_config"]
+        assert handle.spec.config.model_name == data["original_model_name"]
+
+    def test_custom_config_path(self, truss_dir_with_multiple_configs):
+        """Test that TrussHandle with config_path loads from that file."""
+        data = truss_dir_with_multiple_configs
+        handle = TrussHandle(data["truss_dir"], config_path=data["alt_config"])
+
+        # Should load from alternate config
+        assert handle.spec.config_path == data["alt_config"]
+        assert handle.spec.config.model_name == "alternate-model"
+
+    def test_update_config_preserves_custom_config_path(
+        self, truss_dir_with_multiple_configs
+    ):
+        """Test that _update_config preserves the custom config path after reload."""
+        data = truss_dir_with_multiple_configs
+        handle = TrussHandle(data["truss_dir"], config_path=data["alt_config"])
+
+        # Update the config (this triggers a reload)
+        handle._update_config(description="Test description")
+
+        # After reload, should still use the custom config path
+        assert handle.spec.config_path == data["alt_config"]
+        assert handle.spec.config.model_name == "alternate-model"
+        assert handle.spec.config.description == "Test description"
+
+
+class TestLoadFunctionCustomConfigPath:
+    """Tests for the load() function with custom config path."""
+
+    def test_load_default_config_path_backwards_compatibility(
+        self, truss_dir_with_multiple_configs
+    ):
+        """Test that load() without config_path uses default config.yaml."""
+        data = truss_dir_with_multiple_configs
+        handle = load(data["truss_dir"])
+
+        # Should load from default config.yaml
+        assert handle.spec.config_path == data["default_config"]
+        assert handle.spec.config.model_name == data["original_model_name"]
+
+    def test_load_with_custom_config_path(self, truss_dir_with_multiple_configs):
+        """Test that load() with config_path loads from that file."""
+        data = truss_dir_with_multiple_configs
+        handle = load(data["truss_dir"], config_path=data["alt_config"])
+
+        # Should load from alternate config
+        assert handle.spec.config_path == data["alt_config"]
+        assert handle.spec.config.model_name == "alternate-model"
+
+    def test_load_with_external_config_path(self, truss_dir_with_multiple_configs):
+        """Test that load() with external config_path works."""
+        data = truss_dir_with_multiple_configs
+        handle = load(data["truss_dir"], config_path=data["external_config"])
+
+        # Should load from external config
+        assert handle.spec.config_path == data["external_config"]
+        assert handle.spec.config.model_name == "external-model"

truss/truss_handle/build.py

@@ -98,16 +98,20 @@ def init_directory(
     return target_directory_path
 
 
-def load(truss_directory: Union[str, Path]) -> TrussHandle:
+def load(
+    truss_directory: Union[str, Path], config_path: Optional[Path] = None
+) -> TrussHandle:
     """Get a handle to a Truss. A Truss is a build context designed to be built
     as a container locally or uploaded into a model serving environment.
 
     Args:
         truss_directory (str | Path): The local directory of an existing Truss
+        config_path (Path | None): Optional path to a config file. If not provided,
+            defaults to config.yaml in the truss directory.
     Returns:
         TrussHandle
     """
-    return TrussHandle(Path(truss_directory))
+    return TrussHandle(Path(truss_directory), config_path=config_path)
 
 
 def cleanup() -> None:

truss/truss_handle/truss_handle.py

@@ -120,9 +120,12 @@ def __init__(self, base_url):
 
 
 class TrussHandle:
-    def __init__(self, truss_dir: Path, validate: bool = True) -> None:
+    def __init__(
+        self, truss_dir: Path, validate: bool = True, config_path: Optional[Path] = None
+    ) -> None:
         self._truss_dir = truss_dir
-        self._spec = TrussSpec(self._truss_dir)
+        self._config_path = config_path
+        self._spec = TrussSpec(self._truss_dir, config_path=config_path)
         self._hash_for_mod_time: Optional[Tuple[float, str]] = None
         if validate:
             self.validate()
@@ -939,7 +942,9 @@ def _build_image(
     def _update_config(self, **fields_to_update):
         config = self._spec.config.model_copy(update=fields_to_update)
         config.write_to_yaml_file(self._spec.config_path)
-        self._spec = TrussSpec(self._truss_dir)  # Reload.
+        self._spec = TrussSpec(
+            self._truss_dir, config_path=self._config_path
+        )  # Reload.
 
     def _try_patch(self) -> Optional["Container"]:
         if not self.is_control_truss: