Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

feat(eval): add --format=json for structured template output (#3106)

Maximilian Roosc9cfc1ef16c2
diff --git a/docs/content/step.md b/docs/content/step.md
index 217fef054..3b9b8569b 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -567,6 +567,18 @@ Usage: <b><span class=c>wt step eval</span></b> <span class=c>[OPTIONS]</span> <
<b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
Print help (see a summary with &#39;-h&#39;)
+<b><span class=g>Automation:</span></b>
+ <b><span class=c>--format</span></b><span class=c> &lt;FORMAT&gt;</span>
+ Output format
+
+ JSON prints <b>{name, template, result}</b> to stdout instead of the bare result.
+
+ Possible values:
+ - <b><span class=c>text</span></b>: Human-readable text output
+ - <b><span class=c>json</span></b>: JSON output
+
+ [default: text]
+
<b><span class=g>Global Options:</span></b>
<b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 3d82fb56b..e791829db 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -584,6 +584,18 @@ Options:
-h, --help
Print help (see a summary with '-h')
+Automation:
+ --format <FORMAT>
+ Output format
+
+ JSON prints {name, template, result} to stdout instead of the bare result.
+
+ Possible values:
+ - text: Human-readable text output
+ - json: JSON output
+
+ [default: text]
+
Global Options:
-C <path>
Working directory for this command
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 7fd5cca7b..c1426b063 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -452,6 +452,12 @@ Note: This command is experimental and may change in future versions.
Eval {
/// Template expression to evaluate
template: String,
+
+ /// Output format
+ ///
+ /// JSON prints `{name, template, result}` to stdout instead of the bare result.
+ #[arg(long, default_value = "text", help_heading = "Automation")]
+ format: crate::cli::SwitchFormat,
},
/// \[experimental\] Run command in each worktree
diff --git a/src/commands/eval.rs b/src/commands/eval.rs
index 3c0e13b5f..277ec7f88 100644
--- a/src/commands/eval.rs
+++ b/src/commands/eval.rs
@@ -11,18 +11,24 @@ use worktrunk::git::Repository;
use worktrunk::shell_exec::ShellEscapeMode;
use worktrunk::styling::{eprintln, format_with_gutter, info_message, println, verbosity};
+use crate::cli::SwitchFormat;
use crate::commands::command_executor::{CommandContext, build_hook_context};
+/// Template name reported in errors, the `-v` expansion view, and JSON output.
+const EVAL_NAME: &str = "eval";
+
/// Evaluate a template expression in the current worktree context.
///
-/// Prints the expanded result to stdout with a trailing newline. All hook
-/// template variables and filters are available.
+/// In text mode, prints the expanded result to stdout with a trailing newline.
+/// In JSON mode (`--format=json`), prints `{name, template, result}` instead.
+/// All hook template variables and filters are available.
///
/// `eval` mutates nothing, so it has no `--dry-run`. Variable discovery lives
/// in the verbose lane instead: `-v` lists the available template variables on
/// stderr, above the labeled `source` / `result` expansion view that
-/// `expand_template` renders at `-v`.
-pub fn step_eval(template: &str) -> anyhow::Result<()> {
+/// `expand_template` renders at `-v`. The `-v` lane writes to stderr, so it
+/// composes with either output format.
+pub fn step_eval(template: &str, format: SwitchFormat) -> anyhow::Result<()> {
let repo = Repository::current()?;
let config = UserConfig::load()?;
@@ -54,12 +60,23 @@ pub fn step_eval(template: &str) -> anyhow::Result<()> {
.map(|(k, v)| (k.as_str(), v.as_str()))
.collect();
- let result = expand_template(template, &vars, ShellEscapeMode::Literal, &repo, "eval")?;
+ let result = expand_template(template, &vars, ShellEscapeMode::Literal, &repo, EVAL_NAME)?;
// `expand_template` emitted the `source` / `result` view to stderr under
// `-v`; a trailing blank separates it from the result printed below.
if verbosity() >= 1 {
eprintln!();
}
- println!("{result}");
+
+ match format {
+ SwitchFormat::Text => println!("{result}"),
+ SwitchFormat::Json => {
+ let payload = serde_json::json!({
+ "name": EVAL_NAME,
+ "template": template,
+ "result": result,
+ });
+ println!("{}", serde_json::to_string_pretty(&payload)?);
+ }
+ }
Ok(())
}
diff --git a/src/main.rs b/src/main.rs
index eda8298cf..9429d3121 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -363,7 +363,7 @@ fn handle_step_command(action: StepCommand, yes: bool) -> anyhow::Result<()> {
force,
format,
} => step_copy_ignored(from.as_deref(), to.as_deref(), dry_run, force, format),
- StepCommand::Eval { template } => step_eval(&template),
+ StepCommand::Eval { template, format } => step_eval(&template, format),
StepCommand::ForEach { format, args } => step_for_each(args, format),
StepCommand::Promote { branch } => {
handle_promote(branch.as_deref()).map(|result| match result {
diff --git a/tests/integration_tests/eval.rs b/tests/integration_tests/eval.rs
index 0373d7baf..85815b321 100644
--- a/tests/integration_tests/eval.rs
+++ b/tests/integration_tests/eval.rs
@@ -68,6 +68,29 @@ fn test_eval_verbose(repo: TestRepo) {
));
}
+#[rstest]
+fn test_eval_format_json(repo: TestRepo) {
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["eval", "--format=json", "{{ branch | hash_port }}"],
+ None,
+ ));
+}
+
+/// `--format=json` and `-v` compose: JSON to stdout, the human expansion view
+/// to stderr.
+#[rstest]
+fn test_eval_format_json_verbose(repo: TestRepo) {
+ assert_cmd_snapshot!(make_snapshot_cmd_with_global_flags(
+ &repo,
+ "step",
+ &["eval", "--format=json", "{{ branch | hash_port }}"],
+ None,
+ &["--verbose"],
+ ));
+}
+
#[rstest]
fn test_eval_owner(repo: TestRepo) {
repo.run_git(&[
diff --git a/tests/snapshots/integration__integration_tests__eval__eval_format_json.snap b/tests/snapshots/integration__integration_tests__eval__eval_format_json.snap
new file mode 100644
index 000000000..686a5d3fa
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__eval__eval_format_json.snap
@@ -0,0 +1,55 @@
+---
+source: tests/integration_tests/eval.rs
+info:
+ program: wt
+ args:
+ - step
+ - eval
+ - "--format=json"
+ - "{{ branch | hash_port }}"
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_BASH_INSTALLED: "0"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_CODEX_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_FISH_INSTALLED: "0"
+ WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WORKTRUNK_TEST_ZSH_INSTALLED: "0"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+{
+ "name": "eval",
+ "result": "12107",
+ "template": "{{ branch | hash_port }}"
+}
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__eval__eval_format_json_verbose.snap b/tests/snapshots/integration__integration_tests__eval__eval_format_json_verbose.snap
new file mode 100644
index 000000000..e58a3161f
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__eval__eval_format_json_verbose.snap
@@ -0,0 +1,78 @@
+---
+source: tests/integration_tests/eval.rs
+info:
+ program: wt
+ args:
+ - "--verbose"
+ - step
+ - eval
+ - "--format=json"
+ - "{{ branch | hash_port }}"
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_BASH_INSTALLED: "0"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_CODEX_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_FISH_INSTALLED: "0"
+ WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WORKTRUNK_TEST_ZSH_INSTALLED: "0"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+{
+ "name": "eval",
+ "result": "12107",
+ "template": "{{ branch | hash_port }}"
+}
+
+----- stderr -----
+○ Available template variables
+  branch = main
+  commit = 05a4a45d0b981dad5c27db59dca482836d59f89e
+  cwd = _REPO_
+  default_branch = main
+  main_worktree = repo
+  main_worktree_path = _REPO_
+  primary_worktree_path = _REPO_
+  remote = origin
+  remote_url = ../origin.git
+  repo = repo
+  repo_path = _REPO_
+  repo_root = _REPO_
+  short_commit = 05a4a45
+  upstream = origin/main
+  worktree = _REPO_
+  worktree_name = repo
+  worktree_path = _REPO_
+○ eval source
+  {{ branch | hash_port }}
+○ eval result
+  12107