fix: keep --json output parseable on stdout

crates/tower-cmd/src/output.rs

@@ -487,6 +487,25 @@ pub fn list<T: Serialize>(items: Vec<String>, json_data: Option<&T>) {
  }
 }
 
+/// Writes a human-readable rendering of some data, or the data itself as JSON when
+/// in JSON mode. Use this when a command's output is data that has both a plain text
+/// and a JSON representation, mirroring `table` and `list`.
+pub fn text<T: Serialize>(msg: &str, json_data: &T) {
+ if get_output_mode().is_json() {
+ json(json_data);
+ } else {
+ write(msg);
+ }
+}
+
+/// Writes presentation-only text that accompanies human-formatted output, like table
+/// legends or hints. Suppressed in JSON mode so stdout stays machine-parseable.
+pub fn note(msg: &str) {
+ if !get_output_mode().is_json() {
+ write(msg);
+ }
+}
+
 pub fn banner() {
  write(&BANNER_TEXT);
 }

crates/tower-cmd/src/run.rs

@@ -86,11 +86,14 @@ pub async fn do_run(config: Config, args: &ArgMatches) {
  tower_api::apis::Error::ResponseError(resp) if resp.status == reqwest::StatusCode::NOT_FOUND
  );
  if is_not_found {
- output::error("App not found. It may not exist or hasn't been deployed yet.");
- output::write("\nTo fix this:\n");
- output::write(" 1. Check your app exists: tower apps list\n");
- output::write(" 2. Deploy your app: tower deploy\n");
- output::write(" 3. Then run it: tower run\n");
+ output::error(concat!(
+ "App not found. It may not exist or hasn't been deployed yet.\n",
+ "\n",
+ "To fix this:\n",
+ " 1. Check your app exists: tower apps list\n",
+ " 2. Deploy your app: tower deploy\n",
+ " 3. Then run it: tower run"
+ ));
  std::process::exit(1);
  }
  if let Error::ApiRunError { source } = e {
@@ -374,14 +377,10 @@ pub async fn do_run_remote(
  do_follow_run(config, &run).await?;
  } else {
  let line = format!(
- "Run #{} for app `{}` has been scheduled",
- run.number, app_slug
+ "Run #{} for app `{}` has been scheduled\n See more: {}",
+ run.number, app_slug, run.dollar_link
  );
- output::success(&line);
-
- let link_line = format!(" See more: {}", run.dollar_link);
- output::write(&link_line);
- output::newline();
+ output::success_with_data(&line, Some(&run));
  }
  Ok(())
 }

crates/tower-cmd/src/schedules.rs

@@ -121,7 +121,7 @@ pub async fn do_list(config: Config, args: &ArgMatches) {
  .await;
 
  if schedules.is_empty() {
- output::write("No schedules found.\n");
+ output::text("No schedules found.\n", &schedules);
  return;
  }
 

crates/tower-cmd/src/teams.rs

@@ -100,7 +100,10 @@ async fn do_list_via_session(config: &Config) {
  output::newline();
 
  // Add a legend for the asterisk
- println!("{}", "* indicates currently active team".dimmed());
+ output::note(&format!(
+ "{}\n",
+ "* indicates currently active team".dimmed()
+ ));
  output::newline();
 }
 

crates/tower-cmd/src/version.rs

@@ -6,6 +6,9 @@ pub fn version_cmd() -> Command {
 }
 
 pub async fn do_version() {
- let line = format!("v{}\n", tower_version::current_version());
- output::write(&line);
+ let version = tower_version::current_version();
+ output::text(
+ &format!("v{}\n", version),
+ &serde_json::json!({ "version": version }),
+ );
 }

tests/integration/features/cli_json_output.feature

@@ -0,0 +1,31 @@
+Feature: CLI JSON Output
+ As a developer scripting against the Tower CLI
+ I want --json output to be valid JSON on stdout
+ So that I can pipe it into jq or parse it programmatically
+
+ Scenario: Detached run with JSON mode emits parseable output with the run link
+ Given I have a valid Towerfile in the current directory
+ When I run "tower deploy --create" via CLI
+ And I run "tower run --detached --json" via CLI
+ Then the output should be valid JSON
+ And the output should show "See more"
+
+ Scenario: Run of an unknown app with JSON mode emits a parseable error
+ Given I have a simple hello world application
+ When I run "tower run --json" via CLI
+ Then the output should be valid JSON
+ And the output should show "tower deploy"
+
+ Scenario: Empty schedules list with JSON mode emits an empty JSON array
+ When I run "tower schedules list --json" via CLI
+ Then the output should be valid JSON
+ And the JSON should be an empty array
+
+ Scenario: Teams list with JSON mode emits parseable output
+ When I run "tower teams list --json" via CLI with a temporary session
+ Then the output should be valid JSON
+
+ Scenario: Version with JSON mode emits parseable output
+ When I run "tower version --json" via CLI
+ Then the output should be valid JSON
+ And the output should show "version"

tests/integration/features/steps/cli_steps.py

@@ -94,6 +94,28 @@ def step_run_cli_command_with_api_key_and_input(context, command, input):
  return run_command_with_env(context, command, test_env, input=input)
 
 
+@step('I run "{command}" via CLI with a temporary session')
+def step_run_cli_command_with_temp_session(context, command):
+ """Run a Tower CLI command with HOME pointing at a copy of the test session.
+
+ Use this for commands that rewrite session.json (e.g. anything that refreshes
+ the session), so they don't modify the tracked test-home fixture.
+ """
+ test_env = os.environ.copy()
+ test_env["FORCE_COLOR"] = "1"
+ test_env["CLICOLOR_FORCE"] = "1"
+ test_env["TOWER_URL"] = context.tower_url
+
+ test_home = Path(__file__).parent.parent.parent / "test-home"
+ session_src = test_home / ".config" / "tower" / "session.json"
+ session_dst_dir = Path(context.temp_dir) / ".config" / "tower"
+ session_dst_dir.mkdir(parents=True, exist_ok=True)
+ shutil.copy(session_src, session_dst_dir / "session.json")
+ test_env["HOME"] = context.temp_dir
+
+ return run_command_with_env(context, command, test_env)
+
+
 @step("no session.json should exist in the temp home")
 def step_no_session_json(context):
  """Verify that API key auth did not create a session.json file"""
@@ -346,6 +368,13 @@ def step_output_should_be_valid_json(context):
  )
 
 
+@step("the JSON should be an empty array")
+def step_json_should_be_empty_array(context):
+ """Verify JSON output is an empty array"""
+ data = parse_cli_json(context)
+ assert data == [], f"Expected an empty JSON array, got: {data}"
+
+
 @step("the JSON should contain app information")
 def step_json_should_contain_app_info(context):
  """Verify JSON contains app-related information"""

tests/mock-api-server/main.py

@@ -559,16 +559,48 @@ async def get_session():
 
 @app.post("/v1/session/refresh")
 async def refresh_session(refresh_params: Dict[str, Any] = None):
- """Mock endpoint for refreshing session."""
+ """
+ Mock endpoint for refreshing session.
+
+ IMPORTANT: This response format must match the OpenAPI-generated models in:
+ - crates/tower-api/src/models/refresh_session_response.rs
+ - crates/tower-api/src/models/session.rs
+ - crates/tower-api/src/models/team.rs
+ """
  return {
- "user": {"id": "mock_user_id", "email": "test@example.com"},
- "teams": [
- {"name": "default", "type": "user", "token": {"jwt": "mock_jwt_token"}}
- ],
- "active_team": {
- "name": "default",
- "type": "user",
- "token": {"jwt": "mock_jwt_token"},
+ "refreshed_at": "2023-01-01T00:00:00Z",
+ "session": {
+ "featurebase_identity": {
+ "company_hash": "mock_company_hash",
+ "user_hash": "mock_user_hash",
+ },
+ "user": {
+ "company": "Mock Company",
+ "country": "US",
+ "created_at": "2023-01-01T00:00:00Z",
+ "email": "test@example.com",
+ "first_name": "Test",
+ "is_alerts_enabled": True,
+ "is_confirmed": True,
+ "is_invitation_claimed": True,
+ "is_subscribed_to_changelog": False,
+ "last_name": "User",
+ "profile_photo_url": "https://example.com/photo.jpg",
+ "promo_code": "",
+ },
+ "teams": [
+ {
+ "name": "test-team",
+ "type": "personal",
+ "execution_region": "us-east-1",
+ "organization": "",
+ "token": {
+ "access_token": "mock_access_token",
+ "jwt": "mock_jwt_token",
+ },
+ }
+ ],
+ "token": {"access_token": "mock_access_token", "jwt": "mock_jwt_token"},
  },
  }