sam-authoring

name	sam-authoring
description	Guide for authoring SAM aliases and vars files. Use when a user wants to create, edit, or review aliases.yaml or vars.yaml files for SAM, add new aliases to a .sam folder, or structure a new SAM namespace.

SAM Alias Authoring

File placement and namespaces

Place files under any directory declared as root_dir in ~/.sam_rc.toml. The parent directory name becomes the namespace automatically:

~/.sam/
├── aliases.yaml        # no namespace → my_alias
├── vars.yaml
└── docker/
    ├── aliases.yaml    # namespace: docker → docker::my_alias
    └── vars.yaml       # namespace: docker → docker::my_var

A local .sam_rc.toml in the current directory overrides the global one — useful for project-scoped aliases.

aliases.yaml schema

- name: deploy                          # required, no spaces
  desc: Tag and push image              # required
  alias: docker push {{ image }}:{{ tag }}  # required; use {{ var }} and [[ ns::alias ]]

• Reference vars with {{ var_name }} or {{ namespace::var_name }}
• Embed other aliases with [[ namespace::alias_name ]]
• SAM resolves all dependencies before execution

vars.yaml schema

Three mutually exclusive modes:

# Static choices
- name: environment
  desc: target environment
  choices:
    - value: staging
      desc: staging environment
    - value: production

# Dynamic choices — from_command MUST be read-only (no side effects)
- name: container
  desc: a running Docker container
  from_command: 'docker ps --format="{{.ID}}\t{{.Names}}"'

# Templated command — declare dependency explicitly via {{ var }}
- name: container_ip
  desc: IP of the selected container
  from_command: "docker inspect {{ container }} | jq -r '.[0].NetworkSettings.IPAddress'"

# Free-text input
- name: tag
  desc: Docker image tag
  from_input: "enter a tag (e.g. v1.2.3)"

Critical constraint: vars are read-only

from_command values must be pure read operations — no writes, no mutations, no side effects. SAM caches command output and may replay or skip execution; a command that modifies state will produce unpredictable results.

Good: docker ps, kubectl get pods, git branch, gh issue list Bad: docker rm ..., kubectl delete ..., git commit ...

Dependency resolution

SAM detects {{ var }} references inside from_command and prompts for dependencies first — no explicit ordering needed. Cross-namespace references work everywhere: {{ kubernetes::registry }}.