feat(cli): output flags for ps and images (--format/-q, ps -a)

ps and images had no flags. Add docker compose's output controls:
- ps: -a/--all (default now running-only, matching docker), -q/--quiet
  (container IDs), --format table|json
- images: -q/--quiet (image IDs), --format table|json

Non-breaking: existing Engine::ps/images kept as default-option wrappers;
overrides go through ps_with_options/images_with_options. Adds an Id field
to ContainerListEntry for -q.

Closes #412.

Signed-off-by: Jaro-c <75870284+Jaro-c@users.noreply.github.com>

Author: Jaro-c

internal/cli.rs

@@ -2,10 +2,20 @@
 
 use std::path::PathBuf;
 
-use clap::{Parser, Subcommand};
+use clap::{Parser, Subcommand, ValueEnum};
 #[cfg(feature = "completions")]
 use clap_complete::Shell;
 
+/// Output rendering for list commands (`ps`, `images`).
+#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, ValueEnum)]
+pub(crate) enum OutputFormat {
+	/// Aligned columns for human reading.
+	#[default]
+	Table,
+	/// Machine-readable JSON array.
+	Json,
+}
+
 #[derive(Parser)]
 #[command(name = "podup", version)]
 pub(crate) struct Cli {
@@ -187,7 +197,17 @@ pub(crate) enum Commands {
 		dst: String,
 	},
 	/// List containers.
-	Ps,
+	Ps {
+		/// Show all containers, including stopped ones.
+		#[arg(short, long)]
+		all: bool,
+		/// Only display container IDs.
+		#[arg(short, long)]
+		quiet: bool,
+		/// Output format.
+		#[arg(long, value_enum, default_value_t = OutputFormat::Table)]
+		format: OutputFormat,
+	},
 	/// Display the running processes of service containers.
 	Top {
 		/// Show only these services.
@@ -206,7 +226,14 @@ pub(crate) enum Commands {
 	},
 	/// List images used by services.
 	#[command(alias = "image")]
-	Images,
+	Images {
+		/// Only display image IDs.
+		#[arg(short, long)]
+		quiet: bool,
+		/// Output format.
+		#[arg(long, value_enum, default_value_t = OutputFormat::Table)]
+		format: OutputFormat,
+	},
 	/// View output from containers.
 	#[command(alias = "log")]
 	Logs {

internal/engine/mod.rs

@@ -8,7 +8,7 @@ mod copy;
 pub use build::BuildOptions;
 pub use lifecycle::RunOptions;
 pub use lock::ProjectLock;
-pub use query::ExecOptions;
+pub use query::{ExecOptions, ImagesOptions, PsOptions};
 mod container_config;
 mod container_fields;
 mod health;

internal/engine/query/inspect.rs

@@ -98,12 +98,21 @@ impl Engine {
 		Ok(())
 	}
 
-	/// List images used by each service.
+	/// List images used by each service as a table (default options).
 	pub async fn images(&self, file: &ComposeFile) -> Result<()> {
-		println!(
-			"{:<30} {:<25} {:<15} {:<20}",
-			"SERVICE", "REPOSITORY", "TAG", "IMAGE ID"
-		);
+		self.images_with_options(file, super::ImagesOptions::default())
+			.await
+	}
+
+	/// List service images with `docker compose images`-style options:
+	/// `-q/--quiet` (IDs only) and `--format` (table | json).
+	pub async fn images_with_options(
+		&self,
+		file: &ComposeFile,
+		opts: super::ImagesOptions,
+	) -> Result<()> {
+		// Collect rows first so quiet/json modes can render without the header.
+		let mut rows: Vec<(String, String, String, String)> = Vec::new();
 		for (name, service) in &file.services {
 			let image_ref = match &service.image {
 				Some(img) => img.clone(),
@@ -118,11 +127,41 @@ impl Engine {
 						.map(|(r, t)| (r.to_string(), t.to_string()))
 						.unwrap_or_else(|| (image_ref.clone(), "latest".to_string()));
 					let id = img.id.trim_start_matches("sha256:").get(..12).unwrap_or("");
-					println!("{name:<30} {repo:<25} {tag:<15} {id:<20}");
+					rows.push((name.clone(), repo, tag, id.to_string()));
 				}
 				Err(e) => tracing::warn!("images {name}: {e}"),
 			}
 		}
+
+		if opts.quiet {
+			for (_, _, _, id) in &rows {
+				println!("{id}");
+			}
+			return Ok(());
+		}
+		if opts.json {
+			let json: Vec<_> = rows
+				.iter()
+				.map(|(svc, repo, tag, id)| {
+					serde_json::json!({
+						"Service": svc, "Repository": repo, "Tag": tag, "ID": id,
+					})
+				})
+				.collect();
+			println!(
+				"{}",
+				serde_json::to_string_pretty(&json).unwrap_or_default()
+			);
+			return Ok(());
+		}
+
+		println!(
+			"{:<30} {:<25} {:<15} {:<20}",
+			"SERVICE", "REPOSITORY", "TAG", "IMAGE ID"
+		);
+		for (svc, repo, tag, id) in &rows {
+			println!("{svc:<30} {repo:<25} {tag:<15} {id:<20}");
+		}
 		Ok(())
 	}
 

internal/engine/query/mod.rs

@@ -30,13 +30,40 @@ pub struct ExecOptions {
 	pub index: Option<u32>,
 }
 
+/// Options for [`Engine::ps_with_options`].
+#[derive(Default)]
+pub struct PsOptions {
+	/// Include stopped containers, `-a/--all` (default: running only).
+	pub all: bool,
+	/// Print only container IDs, `-q/--quiet`.
+	pub quiet: bool,
+	/// Emit JSON instead of the table, `--format json`.
+	pub json: bool,
+}
+
+/// Options for [`Engine::images_with_options`].
+#[derive(Default)]
+pub struct ImagesOptions {
+	/// Print only image IDs, `-q/--quiet`.
+	pub quiet: bool,
+	/// Emit JSON instead of the table, `--format json`.
+	pub json: bool,
+}
+
 impl Engine {
-	/// List containers for this project: name, image, command, state, and port bindings.
-	pub async fn ps(&self, _file: &ComposeFile) -> Result<()> {
+	/// List running containers for this project as a table (default options).
+	pub async fn ps(&self, file: &ComposeFile) -> Result<()> {
+		self.ps_with_options(file, PsOptions::default()).await
+	}
+
+	/// List containers with `docker compose ps`-style options: `-a/--all`
+	/// (include stopped), `-q/--quiet` (IDs only), and `--format` (table | json).
+	pub async fn ps_with_options(&self, _file: &ComposeFile, opts: PsOptions) -> Result<()> {
 		let label = format!("podup.project={}", self.project);
 		let filters = serde_json::json!({ "label": [label] });
 		let path = format!(
-			"{API_PREFIX}/containers/json?all=true&filters={}",
+			"{API_PREFIX}/containers/json?all={}&filters={}",
+			opts.all,
 			urlencoded(&filters.to_string()),
 		);
 
@@ -46,9 +73,39 @@ impl Engine {
 			.await
 			.map_err(ComposeError::Podman)?;
 
+		let name_of = |c: &crate::libpod::types::container::ContainerListEntry| {
+			c.names.join(", ").trim_start_matches('/').to_string()
+		};
+
+		if opts.quiet {
+			for c in &containers {
+				let id = c.id.get(..12).unwrap_or(&c.id);
+				println!("{id}");
+			}
+			return Ok(());
+		}
+
+		if opts.json {
+			let rows: Vec<_> = containers
+				.iter()
+				.map(|c| {
+					serde_json::json!({
+						"Name": name_of(c),
+						"Image": c.image,
+						"Status": c.status,
+						"ID": c.id,
+					})
+				})
+				.collect();
+			println!(
+				"{}",
+				serde_json::to_string_pretty(&rows).unwrap_or_default()
+			);
+			return Ok(());
+		}
+
 		println!("{:<40} {:<30} {:<20}", "NAME", "IMAGE", "STATUS");
-		for c in containers {
-			let names = c.names.join(", ").trim_start_matches('/').to_string();
+		for c in &containers {
 			let ports = c
 				.ports
 				.iter()
@@ -62,7 +119,12 @@ impl Engine {
 				})
 				.collect::<Vec<_>>()
 				.join(", ");
-			println!("{names:<40} {:<30} {:<20} {ports}", c.image, c.status);
+			println!(
+				"{:<40} {:<30} {:<20} {ports}",
+				name_of(c),
+				c.image,
+				c.status
+			);
 		}
 
 		Ok(())

internal/lib.rs

@@ -29,7 +29,8 @@ pub use compose::{
 	parse_str, parse_str_raw, resolve_levels, resolve_order,
 };
 pub use engine::{
-	is_safe_project_name, BuildOptions, Engine, ExecOptions, ProjectLock, RunOptions,
+	is_safe_project_name, BuildOptions, Engine, ExecOptions, ImagesOptions, ProjectLock, PsOptions,
+	RunOptions,
 };
 pub use error::{ComposeError, Result};
 pub use libpod::Client;

internal/libpod/types/container/response.rs

@@ -19,6 +19,9 @@ where
 /// Entry in the `GET /libpod/containers/json` response array.
 #[derive(Deserialize)]
 pub struct ContainerListEntry {
+	#[serde(rename = "Id", default)]
+	pub id: String,
+
 	#[serde(rename = "Names", default, deserialize_with = "null_default")]
 	pub names: Vec<String>,
 

internal/main.rs

@@ -384,14 +384,35 @@ async fn run() -> podup::Result<()> {
 				.await?
 		}
 		Commands::Cp { src, dst } => engine.cp(&file, &src, &dst).await?,
-		Commands::Ps => engine.ps(&file).await?,
+		Commands::Ps { all, quiet, format } => {
+			engine
+				.ps_with_options(
+					&file,
+					podup::PsOptions {
+						all,
+						quiet,
+						json: format == OutputFormat::Json,
+					},
+				)
+				.await?
+		}
 		Commands::Top { services } => engine.top(&file, &services).await?,
 		Commands::Port {
 			service,
 			private_port,
 			proto,
 		} => engine.port(&file, &service, private_port, &proto).await?,
-		Commands::Images => engine.images(&file).await?,
+		Commands::Images { quiet, format } => {
+			engine
+				.images_with_options(
+					&file,
+					podup::ImagesOptions {
+						quiet,
+						json: format == OutputFormat::Json,
+					},
+				)
+				.await?
+		}
 		Commands::Logs { service, follow } => {
 			engine.logs(&file, service.as_deref(), follow).await?
 		}

tests/cli_aliases.rs

@@ -127,3 +127,25 @@ fn build_accepts_override_flags() {
 		);
 	}
 }
+
+/// `ps` and `images` expose output flags (`--format`, `-q/--quiet`; `ps` also
+/// `-a/--all`) so their output can be scripted against.
+#[test]
+fn ps_and_images_expose_output_flags() {
+	let ps = Command::new(bin()).args(["ps", "--help"]).output().unwrap();
+	let ps_out = String::from_utf8_lossy(&ps.stdout);
+	for flag in ["--all", "--quiet", "--format"] {
+		assert!(ps_out.contains(flag), "`ps` missing {flag}:\n{ps_out}");
+	}
+	let img = Command::new(bin())
+		.args(["images", "--help"])
+		.output()
+		.unwrap();
+	let img_out = String::from_utf8_lossy(&img.stdout);
+	for flag in ["--quiet", "--format"] {
+		assert!(
+			img_out.contains(flag),
+			"`images` missing {flag}:\n{img_out}"
+		);
+	}
+}