proxctl 0.2.4__tar.gz → 0.2.6__tar.gz

{proxctl-0.2.4 → proxctl-0.2.6}/CHANGELOG.md

@@ -6,6 +6,20 @@ All notable changes to this project will be documented in this file.
 
 
 
+
+
+## [0.2.6](https://github.com/rvben/proxctl/compare/v0.2.5...v0.2.6) - 2026-04-03
+
+### Added
+
+- add --limit, --offset, --fields to all list commands ([0ecd684](https://github.com/rvben/proxctl/commit/0ecd6844273d697dcc1f7247f26743d6ac8252af))
+
+## [0.2.5](https://github.com/rvben/proxctl/compare/v0.2.4...v0.2.5) - 2026-04-03
+
+### Added
+
+- add error kinds to schema and structured JSON errors on stderr ([b46b7d6](https://github.com/rvben/proxctl/commit/b46b7d67d0a40412ffb90771e221e5dbf9b08f73))
+
 ## [0.2.4](https://github.com/rvben/proxctl/compare/v0.2.3...v0.2.4) - 2026-04-03
 
 ### Added

{proxctl-0.2.4 → proxctl-0.2.6}/Cargo.lock

@@ -955,7 +955,7 @@ dependencies = [
 
 [[package]]
 name = "proxctl"
-version = "0.2.4"
+version = "0.2.6"
 dependencies = [
  "clap",
  "clap_complete",

{proxctl-0.2.4 → proxctl-0.2.6}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "proxctl"
-version = "0.2.4"
+version = "0.2.6"
 edition = "2024"
 rust-version = "1.90"
 description = "CLI for Proxmox VE"

{proxctl-0.2.4 → proxctl-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxctl
-Version: 0.2.4
+Version: 0.2.6
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: System Administrators

{proxctl-0.2.4 → proxctl-0.2.6}/src/api/error.rs

@@ -40,6 +40,19 @@ pub enum Error {
 }
 
 impl Error {
+    /// Returns a machine-readable error kind string for structured error output.
+    pub fn kind(&self) -> &'static str {
+        match self {
+            Error::Config(_) => "config",
+            Error::Auth(_) => "auth",
+            Error::NotFound(_) => "not_found",
+            Error::Api { .. } | Error::TaskFailed(_) => "api",
+            Error::Conflict(_) => "conflict",
+            Error::Timeout(_) => "timeout",
+            Error::Http(_) | Error::Other(_) => "other",
+        }
+    }
+
     pub fn exit_code(&self) -> i32 {
         match self {
             Error::Config(_) => exit_codes::CONFIG_ERROR,
@@ -174,6 +187,25 @@ mod tests {
         assert_eq!(exit_codes::TIMEOUT, 7);
     }
 
+    #[test]
+    fn test_kind_maps_correctly() {
+        assert_eq!(Error::Config("x".into()).kind(), "config");
+        assert_eq!(Error::Auth("x".into()).kind(), "auth");
+        assert_eq!(Error::NotFound("x".into()).kind(), "not_found");
+        assert_eq!(
+            Error::Api {
+                status: 500,
+                message: "x".into()
+            }
+            .kind(),
+            "api"
+        );
+        assert_eq!(Error::TaskFailed("x".into()).kind(), "api");
+        assert_eq!(Error::Conflict("x".into()).kind(), "conflict");
+        assert_eq!(Error::Timeout("x".into()).kind(), "timeout");
+        assert_eq!(Error::Other("x".into()).kind(), "other");
+    }
+
     #[test]
     fn test_error_display_config() {
         let err = Error::Config("missing host".to_string());

{proxctl-0.2.4 → proxctl-0.2.6}/src/commands/backup.rs

@@ -4,6 +4,7 @@ use serde_json::json;
 
 use crate::api::Error;
 use crate::api::client::ProxmoxClient;
+use crate::commands::list_args::ListArgs;
 use crate::output::{OutputConfig, use_color};
 
 fn require_node<'a>(node: Option<&'a str>, global_node: Option<&'a str>) -> Result<&'a str, Error> {
@@ -69,6 +70,8 @@ pub enum BackupCommand {
         /// Node name
         #[arg(long)]
         node: Option<String>,
+        #[command(flatten)]
+        list: ListArgs,
     },
     /// Create a backup
     Create {
@@ -128,9 +131,10 @@ pub async fn run(
             vmid,
             storage,
             node,
+            list: list_args,
         } => {
             let n = require_node(node.as_deref(), global_node)?;
-            list(client, out, n, vmid, storage.as_deref()).await
+            list(client, out, n, vmid, storage.as_deref(), &list_args).await
         }
         BackupCommand::Create {
             vmid,
@@ -206,6 +210,7 @@ async fn list(
     node: &str,
     vmid_filter: Option<u32>,
     storage_filter: Option<&str>,
+    list_args: &ListArgs,
 ) -> Result<(), Error> {
     // Find backup-capable storages
     let storages: Vec<serde_json::Value> = client.get(&format!("/nodes/{node}/storage")).await?;
@@ -253,12 +258,19 @@ async fn list(
         });
     }
 
+    let total = all_backups.len();
+
     if out.json {
-        out.print_data(&serde_json::to_string_pretty(&all_backups).expect("serialize"));
+        let paginated: Vec<serde_json::Value> = list_args.paginate(&all_backups).to_vec();
+        let paginated = list_args.filter_fields(paginated);
+        let envelope = list_args.paginated_json(&paginated, total);
+        out.print_data(&serde_json::to_string_pretty(&envelope).expect("serialize"));
         return Ok(());
     }
 
-    if all_backups.is_empty() {
+    let page = list_args.paginate(&all_backups);
+
+    if page.is_empty() {
         out.print_message("No backups found.");
         return Ok(());
     }
@@ -273,7 +285,7 @@ async fn list(
         println!("{header}");
         println!("{}", "-".repeat(total_w));
     }
-    for b in &all_backups {
+    for b in page {
         let volid = b.get("volid").and_then(|v| v.as_str()).unwrap_or("-");
         let vmid = b
             .get("vmid")

{proxctl-0.2.4 → proxctl-0.2.6}/src/commands/container/lifecycle.rs

@@ -3,6 +3,7 @@ use serde_json::json;
 
 use crate::api::Error;
 use crate::api::client::ProxmoxClient;
+use crate::commands::list_args::ListArgs;
 use crate::output::{OutputConfig, use_color};
 
 /// Format bytes as a human-readable string (e.g. "2.00 GiB").
@@ -47,6 +48,7 @@ pub async fn list(
     node: Option<&str>,
     status_filter: Option<&str>,
     pool_filter: Option<&str>,
+    list_args: &ListArgs,
 ) -> Result<(), Error> {
     let containers: Vec<serde_json::Value> = if let Some(n) = node {
         let items: Vec<serde_json::Value> = client.get(&format!("/nodes/{n}/lxc")).await?;
@@ -69,8 +71,8 @@ pub async fn list(
             .collect()
     };
 
-    let containers: Vec<&serde_json::Value> = containers
-        .iter()
+    let containers: Vec<serde_json::Value> = containers
+        .into_iter()
         .filter(|v| {
             if let Some(sf) = status_filter {
                 let s = v.get("status").and_then(|x| x.as_str()).unwrap_or("");
@@ -88,12 +90,19 @@ pub async fn list(
         })
         .collect();
 
+    let total = containers.len();
+
     if out.json {
-        out.print_data(&serde_json::to_string_pretty(&containers).expect("serialize"));
+        let paginated: Vec<serde_json::Value> = list_args.paginate(&containers).to_vec();
+        let paginated = list_args.filter_fields(paginated);
+        let envelope = list_args.paginated_json(&paginated, total);
+        out.print_data(&serde_json::to_string_pretty(&envelope).expect("serialize"));
         return Ok(());
     }
 
-    if containers.is_empty() {
+    let page = list_args.paginate(&containers);
+
+    if page.is_empty() {
         out.print_message("No containers found.");
         return Ok(());
     }
@@ -112,7 +121,7 @@ pub async fn list(
         println!("{}", "-".repeat(total_w));
     }
 
-    for ct in &containers {
+    for ct in page {
         let vmid = ct.get("vmid").and_then(|v| v.as_u64()).unwrap_or(0);
         let name = ct
             .get("name")

{proxctl-0.2.4 → proxctl-0.2.6}/src/commands/container/mod.rs

@@ -8,6 +8,7 @@ use clap::Subcommand;
 
 use crate::api::Error;
 use crate::api::client::ProxmoxClient;
+use crate::commands::list_args::ListArgs;
 use crate::output::OutputConfig;
 
 #[derive(Subcommand)]
@@ -105,6 +106,8 @@ pub enum ContainerCommand {
         /// Filter by pool
         #[arg(long)]
         pool: Option<String>,
+        #[command(flatten)]
+        list: ListArgs,
     },
     /// Show container status
     Status {
@@ -314,7 +317,12 @@ pub async fn run(
     global_node: Option<&str>,
 ) -> Result<(), Error> {
     match cmd {
-        ContainerCommand::List { node, status, pool } => {
+        ContainerCommand::List {
+            node,
+            status,
+            pool,
+            list,
+        } => {
             let effective_node = node.as_deref().or(global_node);
             lifecycle::list(
                 client,
@@ -322,6 +330,7 @@ pub async fn run(
                 effective_node,
                 status.as_deref(),
                 pool.as_deref(),
+                &list,
             )
             .await
         }

proxctl-0.2.6/src/commands/list_args.rs

@@ -0,0 +1,67 @@
+use std::collections::HashSet;
+
+use serde_json::json;
+
+/// Shared arguments for list commands providing bounded output support.
+#[derive(clap::Args, Clone, Debug)]
+pub struct ListArgs {
+    /// Maximum number of items to return
+    #[arg(long)]
+    pub limit: Option<usize>,
+
+    /// Number of items to skip
+    #[arg(long, default_value = "0")]
+    pub offset: usize,
+
+    /// Comma-separated list of fields to include in JSON output
+    #[arg(long)]
+    pub fields: Option<String>,
+}
+
+impl ListArgs {
+    /// Apply offset and limit to a slice, returning a paginated subset.
+    pub fn paginate<'a, T>(&self, items: &'a [T]) -> &'a [T] {
+        let start = self.offset.min(items.len());
+        let remaining = &items[start..];
+        match self.limit {
+            Some(limit) => &remaining[..limit.min(remaining.len())],
+            None => remaining,
+        }
+    }
+
+    /// Filter JSON values to only include specified fields.
+    /// Returns items unchanged if no fields filter is set.
+    pub fn filter_fields(&self, items: Vec<serde_json::Value>) -> Vec<serde_json::Value> {
+        let fields = match &self.fields {
+            Some(f) => f,
+            None => return items,
+        };
+
+        let field_set: HashSet<&str> = fields.split(',').map(|f| f.trim()).collect();
+        items
+            .into_iter()
+            .map(|item| {
+                if let Some(obj) = item.as_object() {
+                    let filtered: serde_json::Map<String, serde_json::Value> = obj
+                        .iter()
+                        .filter(|(k, _)| field_set.contains(k.as_str()))
+                        .map(|(k, v)| (k.clone(), v.clone()))
+                        .collect();
+                    serde_json::Value::Object(filtered)
+                } else {
+                    item
+                }
+            })
+            .collect()
+    }
+
+    /// Wrap items in a pagination envelope for JSON output.
+    pub fn paginated_json(&self, items: &[serde_json::Value], total: usize) -> serde_json::Value {
+        json!({
+            "items": items,
+            "total": total,
+            "offset": self.offset,
+            "limit": self.limit,
+        })
+    }
+}

{proxctl-0.2.4 → proxctl-0.2.6}/src/commands/mod.rs

@@ -7,6 +7,7 @@ pub mod cluster;
 pub mod container;
 pub mod export;
 pub mod firewall;
+pub mod list_args;
 pub mod node;
 pub mod pool;
 pub mod storage;

{proxctl-0.2.4 → proxctl-0.2.6}/src/commands/node.rs

@@ -4,6 +4,7 @@ use serde_json::json;
 
 use crate::api::Error;
 use crate::api::client::ProxmoxClient;
+use crate::commands::list_args::ListArgs;
 use crate::output::{OutputConfig, use_color};
 
 #[derive(Subcommand)]
@@ -89,7 +90,10 @@ pub enum CertificateCommand {
 #[derive(Subcommand)]
 pub enum NodeCommand {
     /// List all nodes
-    List,
+    List {
+        #[command(flatten)]
+        list: ListArgs,
+    },
     /// Show node status
     Status {
         /// Node name (uses default node if not specified)
@@ -221,7 +225,7 @@ pub async fn run(
     global_node: Option<&str>,
 ) -> Result<(), Error> {
     match cmd {
-        NodeCommand::List => list(client, out).await,
+        NodeCommand::List { list: list_args } => list(client, out, &list_args).await,
         NodeCommand::Status { node } => {
             let n = require_node(node.as_deref(), global_node)?;
             status(client, out, n).await
@@ -270,15 +274,29 @@ pub async fn run(
     }
 }
 
-async fn list(client: &ProxmoxClient, out: OutputConfig) -> Result<(), Error> {
+async fn list(
+    client: &ProxmoxClient,
+    out: OutputConfig,
+    list_args: &ListArgs,
+) -> Result<(), Error> {
     let nodes = client.list_nodes().await?;
+    let total = nodes.len();
 
     if out.json {
-        out.print_data(&serde_json::to_string_pretty(&nodes).expect("serialize"));
+        let values: Vec<serde_json::Value> = nodes
+            .iter()
+            .map(|n| serde_json::to_value(n).expect("serialize node"))
+            .collect();
+        let paginated: Vec<serde_json::Value> = list_args.paginate(&values).to_vec();
+        let paginated = list_args.filter_fields(paginated);
+        let envelope = list_args.paginated_json(&paginated, total);
+        out.print_data(&serde_json::to_string_pretty(&envelope).expect("serialize"));
         return Ok(());
     }
 
-    if nodes.is_empty() {
+    let page = list_args.paginate(&nodes);
+
+    if page.is_empty() {
         out.print_message("No nodes found.");
         return Ok(());
     }
@@ -297,7 +315,7 @@ async fn list(client: &ProxmoxClient, out: OutputConfig) -> Result<(), Error> {
         println!("{}", "-".repeat(total_w));
     }
 
-    for node in &nodes {
+    for node in page {
         let hours = node.uptime / 3600;
         let days = hours / 24;
         let uptime_str = if days > 0 {

{proxctl-0.2.4 → proxctl-0.2.6}/src/commands/pool.rs

@@ -4,6 +4,7 @@ use serde_json::json;
 
 use crate::api::Error;
 use crate::api::client::ProxmoxClient;
+use crate::commands::list_args::ListArgs;
 use crate::output::{OutputConfig, use_color};
 
 fn confirm_action(action: &str, yes: bool) -> Result<(), Error> {
@@ -25,7 +26,10 @@ fn confirm_action(action: &str, yes: bool) -> Result<(), Error> {
 #[derive(Subcommand)]
 pub enum PoolCommand {
     /// List resource pools
-    List,
+    List {
+        #[command(flatten)]
+        list: ListArgs,
+    },
     /// Show pool details
     Show {
         /// Pool ID
@@ -70,7 +74,7 @@ pub async fn run(
     _global_node: Option<&str>,
 ) -> Result<(), Error> {
     match cmd {
-        PoolCommand::List => list(client, out).await,
+        PoolCommand::List { list: list_args } => list(client, out, &list_args).await,
         PoolCommand::Show { poolid } => show(client, out, &poolid).await,
         PoolCommand::Create { poolid, comment } => {
             create(client, out, &poolid, comment.as_deref()).await
@@ -95,15 +99,25 @@ pub async fn run(
     }
 }
 
-async fn list(client: &ProxmoxClient, out: OutputConfig) -> Result<(), Error> {
+async fn list(
+    client: &ProxmoxClient,
+    out: OutputConfig,
+    list_args: &ListArgs,
+) -> Result<(), Error> {
     let data: Vec<serde_json::Value> = client.get("/pools").await?;
+    let total = data.len();
 
     if out.json {
-        out.print_data(&serde_json::to_string_pretty(&data).expect("serialize"));
+        let paginated: Vec<serde_json::Value> = list_args.paginate(&data).to_vec();
+        let paginated = list_args.filter_fields(paginated);
+        let envelope = list_args.paginated_json(&paginated, total);
+        out.print_data(&serde_json::to_string_pretty(&envelope).expect("serialize"));
         return Ok(());
     }
 
-    if data.is_empty() {
+    let page = list_args.paginate(&data);
+
+    if page.is_empty() {
         out.print_message("No resource pools found.");
         return Ok(());
     }
@@ -118,7 +132,7 @@ async fn list(client: &ProxmoxClient, out: OutputConfig) -> Result<(), Error> {
         println!("{header}");
         println!("{}", "-".repeat(total_w));
     }
-    for pool in &data {
+    for pool in page {
         let poolid = pool.get("poolid").and_then(|v| v.as_str()).unwrap_or("-");
         let comment = pool.get("comment").and_then(|v| v.as_str()).unwrap_or("");
         if color {

{proxctl-0.2.4 → proxctl-0.2.6}/src/commands/storage.rs

@@ -4,6 +4,7 @@ use serde_json::json;
 
 use crate::api::Error;
 use crate::api::client::ProxmoxClient;
+use crate::commands::list_args::ListArgs;
 use crate::output::{OutputConfig, use_color};
 
 fn require_node<'a>(node: Option<&'a str>, global_node: Option<&'a str>) -> Result<&'a str, Error> {
@@ -37,6 +38,8 @@ pub enum StorageCommand {
         /// Filter by storage type
         #[arg(long, rename_all = "kebab-case")]
         r#type: Option<String>,
+        #[command(flatten)]
+        list: ListArgs,
     },
     /// Show storage status
     Status {
@@ -142,12 +145,17 @@ pub async fn run(
     global_node: Option<&str>,
 ) -> Result<(), Error> {
     match cmd {
-        StorageCommand::List { node, r#type } => {
+        StorageCommand::List {
+            node,
+            r#type,
+            list: list_args,
+        } => {
             list(
                 client,
                 out,
                 node.as_deref().or(global_node),
                 r#type.as_deref(),
+                &list_args,
             )
             .await
         }
@@ -231,6 +239,7 @@ async fn list(
     out: OutputConfig,
     node: Option<&str>,
     type_filter: Option<&str>,
+    list_args: &ListArgs,
 ) -> Result<(), Error> {
     let mut data: Vec<serde_json::Value> = client.get("/storage").await?;
 
@@ -250,12 +259,19 @@ async fn list(
         });
     }
 
+    let total = data.len();
+
     if out.json {
-        out.print_data(&serde_json::to_string_pretty(&data).expect("serialize"));
+        let paginated: Vec<serde_json::Value> = list_args.paginate(&data).to_vec();
+        let paginated = list_args.filter_fields(paginated);
+        let envelope = list_args.paginated_json(&paginated, total);
+        out.print_data(&serde_json::to_string_pretty(&envelope).expect("serialize"));
         return Ok(());
     }
 
-    if data.is_empty() {
+    let page = list_args.paginate(&data);
+
+    if page.is_empty() {
         out.print_message("No storage pools found.");
         return Ok(());
     }
@@ -273,7 +289,7 @@ async fn list(
         println!("{header}");
         println!("{}", "-".repeat(total_w));
     }
-    for s in &data {
+    for s in page {
         let name = s.get("storage").and_then(|v| v.as_str()).unwrap_or("-");
         let stype = s.get("type").and_then(|v| v.as_str()).unwrap_or("-");
         let content = s.get("content").and_then(|v| v.as_str()).unwrap_or("-");

{proxctl-0.2.4 → proxctl-0.2.6}/src/commands/task.rs

@@ -4,6 +4,7 @@ use serde_json::json;
 
 use crate::api::Error;
 use crate::api::client::{ProxmoxClient, parse_upid_node};
+use crate::commands::list_args::ListArgs;
 use crate::output::{OutputConfig, use_color};
 
 #[derive(Subcommand)]
@@ -19,6 +20,8 @@ pub enum TaskCommand {
         /// Filter by status (running, error, ok)
         #[arg(long)]
         status: Option<String>,
+        #[command(flatten)]
+        list: ListArgs,
     },
     /// Show task status
     Status {
@@ -56,6 +59,7 @@ pub async fn run(
             node,
             source,
             status,
+            list: list_args,
         } => {
             list(
                 client,
@@ -63,6 +67,7 @@ pub async fn run(
                 node.as_deref().or(global_node),
                 source.as_deref(),
                 status.as_deref(),
+                &list_args,
             )
             .await
         }
@@ -79,6 +84,7 @@ async fn list(
     node: Option<&str>,
     source: Option<&str>,
     status_filter: Option<&str>,
+    list_args: &ListArgs,
 ) -> Result<(), Error> {
     let data: Vec<serde_json::Value> = if let Some(n) = node {
         let mut path = format!("/nodes/{n}/tasks");
@@ -101,8 +107,8 @@ async fn list(
     };
 
     // Apply client-side status filter for ok/error
-    let data: Vec<&serde_json::Value> = data
-        .iter()
+    let data: Vec<serde_json::Value> = data
+        .into_iter()
         .filter(|t| {
             if let Some(sf) = status_filter {
                 match sf {
@@ -128,12 +134,19 @@ async fn list(
         })
         .collect();
 
+    let total = data.len();
+
     if out.json {
-        out.print_data(&serde_json::to_string_pretty(&data).expect("serialize"));
+        let paginated: Vec<serde_json::Value> = list_args.paginate(&data).to_vec();
+        let paginated = list_args.filter_fields(paginated);
+        let envelope = list_args.paginated_json(&paginated, total);
+        out.print_data(&serde_json::to_string_pretty(&envelope).expect("serialize"));
         return Ok(());
     }
 
-    if data.is_empty() {
+    let page = list_args.paginate(&data);
+
+    if page.is_empty() {
         out.print_message("No tasks found.");
         return Ok(());
     }
@@ -151,7 +164,7 @@ async fn list(
         println!("{header}");
         println!("{}", "-".repeat(total_w));
     }
-    for task in &data {
+    for task in page {
         let node_name = task.get("node").and_then(|v| v.as_str()).unwrap_or("-");
         let task_type = task.get("type").and_then(|v| v.as_str()).unwrap_or("-");
         let id = task.get("id").and_then(|v| v.as_str()).unwrap_or("-");

{proxctl-0.2.4 → proxctl-0.2.6}/src/commands/vm/lifecycle.rs

@@ -3,6 +3,7 @@ use serde_json::json;
 
 use crate::api::Error;
 use crate::api::client::ProxmoxClient;
+use crate::commands::list_args::ListArgs;
 use crate::output::{OutputConfig, use_color};
 
 /// Format bytes as a human-readable string (e.g. "2.00 GiB").
@@ -47,6 +48,7 @@ pub async fn list(
     node: Option<&str>,
     status_filter: Option<&str>,
     pool_filter: Option<&str>,
+    list_args: &ListArgs,
 ) -> Result<(), Error> {
     let vms: Vec<serde_json::Value> = if let Some(n) = node {
         let items: Vec<serde_json::Value> = client.get(&format!("/nodes/{n}/qemu")).await?;
@@ -71,8 +73,8 @@ pub async fn list(
     };
 
     // Apply filters
-    let vms: Vec<&serde_json::Value> = vms
-        .iter()
+    let vms: Vec<serde_json::Value> = vms
+        .into_iter()
         .filter(|v| {
             if let Some(sf) = status_filter {
                 let s = v.get("status").and_then(|x| x.as_str()).unwrap_or("");
@@ -90,12 +92,19 @@ pub async fn list(
         })
         .collect();
 
+    let total = vms.len();
+
     if out.json {
-        out.print_data(&serde_json::to_string_pretty(&vms).expect("serialize"));
+        let paginated: Vec<serde_json::Value> = list_args.paginate(&vms).to_vec();
+        let paginated = list_args.filter_fields(paginated);
+        let envelope = list_args.paginated_json(&paginated, total);
+        out.print_data(&serde_json::to_string_pretty(&envelope).expect("serialize"));
         return Ok(());
     }
 
-    if vms.is_empty() {
+    let page = list_args.paginate(&vms);
+
+    if page.is_empty() {
         out.print_message("No virtual machines found.");
         return Ok(());
     }
@@ -114,7 +123,7 @@ pub async fn list(
         println!("{}", "-".repeat(total_w));
     }
 
-    for vm in &vms {
+    for vm in page {
         let vmid = vm.get("vmid").and_then(|v| v.as_u64()).unwrap_or(0);
         let name = vm.get("name").and_then(|v| v.as_str()).unwrap_or("-");
         let status = vm

{proxctl-0.2.4 → proxctl-0.2.6}/src/commands/vm/mod.rs

@@ -10,6 +10,7 @@ use clap::Subcommand;
 
 use crate::api::Error;
 use crate::api::client::ProxmoxClient;
+use crate::commands::list_args::ListArgs;
 use crate::output::OutputConfig;
 
 #[derive(Subcommand)]
@@ -173,6 +174,8 @@ pub enum VmCommand {
         /// Filter by pool
         #[arg(long)]
         pool: Option<String>,
+        #[command(flatten)]
+        list: ListArgs,
     },
     /// Show VM status
     Status {
@@ -393,7 +396,12 @@ pub async fn run(
     global_node: Option<&str>,
 ) -> Result<(), Error> {
     match cmd {
-        VmCommand::List { node, status, pool } => {
+        VmCommand::List {
+            node,
+            status,
+            pool,
+            list,
+        } => {
             let effective_node = node.as_deref().or(global_node);
             lifecycle::list(
                 client,
@@ -401,6 +409,7 @@ pub async fn run(
                 effective_node,
                 status.as_deref(),
                 pool.as_deref(),
+                &list,
             )
             .await
         }

{proxctl-0.2.4 → proxctl-0.2.6}/src/main.rs

@@ -1,3 +1,4 @@
+use std::io::IsTerminal;
 use std::path::PathBuf;
 use std::process;
 
@@ -6,7 +7,6 @@ use clap_complete::Shell;
 use serde_json::json;
 
 use proxctl::api::client::ProxmoxClient;
-use proxctl::api::error::exit_codes;
 use proxctl::api::token::ApiToken;
 use proxctl::commands::access::AccessCommand;
 use proxctl::commands::apply::ApplyCommand;
@@ -760,6 +760,22 @@ async fn run_config_init() -> Result<(), Error> {
     Ok(())
 }
 
+/// Print an error to stderr. When stdout is not a TTY (piped), output
+/// structured JSON so consuming agents can parse error details.
+fn print_error(e: &Error) {
+    if std::io::stdout().is_terminal() {
+        eprintln!("Error: {e}");
+    } else {
+        let json = json!({
+            "error": {
+                "kind": e.kind(),
+                "message": e.to_string(),
+            }
+        });
+        eprintln!("{}", serde_json::to_string(&json).expect("serialize error"));
+    }
+}
+
 // ── Main ────────────────────────────────────────────────────────────
 
 #[tokio::main]
@@ -780,7 +796,7 @@ async fn main() {
         }
         Command::Config(ConfigCommand::Init) => {
             if let Err(e) = run_config_init().await {
-                eprintln!("Error: {e}");
+                print_error(&e);
                 process::exit(e.exit_code());
             }
             return;
@@ -796,15 +812,19 @@ async fn main() {
     let (cfg_host, cfg_token, cfg_insecure) = load_config(cli.profile.as_deref());
 
     let host = cli.host.or(cfg_host).unwrap_or_else(|| {
-        eprintln!("Error: no host configured. Set --host, PROXMOX_HOST, or configure a profile.");
-        process::exit(exit_codes::CONFIG_ERROR);
+        let e = Error::Config(
+            "no host configured. Set --host, PROXMOX_HOST, or configure a profile.".to_string(),
+        );
+        print_error(&e);
+        process::exit(e.exit_code());
     });
 
     let token_str = cli.token.or(cfg_token).unwrap_or_else(|| {
-        eprintln!(
-            "Error: no token configured. Set --token, PROXMOX_TOKEN, or configure a profile."
+        let e = Error::Config(
+            "no token configured. Set --token, PROXMOX_TOKEN, or configure a profile.".to_string(),
         );
-        process::exit(exit_codes::CONFIG_ERROR);
+        print_error(&e);
+        process::exit(e.exit_code());
     });
 
     let insecure = cli.insecure || cfg_insecure.unwrap_or(false);
@@ -812,15 +832,16 @@ async fn main() {
     let token: ApiToken = match token_str.parse() {
         Ok(t) => t,
         Err(e) => {
-            eprintln!("Error: {e}");
-            process::exit(exit_codes::CONFIG_ERROR);
+            let err = Error::Config(e.to_string());
+            print_error(&err);
+            process::exit(err.exit_code());
         }
     };
 
     let client = match ProxmoxClient::new(&host, token, insecure) {
         Ok(c) => c,
         Err(e) => {
-            eprintln!("Error: {e}");
+            print_error(&e);
             process::exit(e.exit_code());
         }
     };
@@ -882,7 +903,7 @@ async fn main() {
     };
 
     if let Err(e) = result {
-        eprintln!("Error: {e}");
+        print_error(&e);
         process::exit(e.exit_code());
     }
 }

{proxctl-0.2.4 → proxctl-0.2.6}/src/schema.rs

@@ -184,6 +184,15 @@ pub fn generate(cmd: &clap::Command) -> Value {
         "version": env!("CARGO_PKG_VERSION"),
         "description": "CLI for Proxmox VE — manage VMs, containers, nodes, storage, and more",
         "usage": "proxctl [OPTIONS] <COMMAND> [SUBCOMMAND] [ARGS]",
+        "errors": [
+            {"kind": "config", "retryable": false, "description": "Configuration error"},
+            {"kind": "auth", "retryable": false, "description": "Authentication failed"},
+            {"kind": "not_found", "retryable": false, "description": "Resource not found"},
+            {"kind": "api", "retryable": true, "description": "API error"},
+            {"kind": "conflict", "retryable": false, "description": "Resource conflict"},
+            {"kind": "timeout", "retryable": true, "description": "Operation timed out"},
+            {"kind": "other", "retryable": false, "description": "General error"}
+        ],
         "global_flags": {
             "--host": {"type": "string", "env": "PROXMOX_HOST", "description": "Proxmox host (e.g., 192.168.1.25:8006)"},
             "--token": {"type": "string", "env": "PROXMOX_TOKEN", "description": "API token (user@realm!tokenid=secret)"},
@@ -443,6 +452,7 @@ mod tests {
         assert!(schema.get("version").is_some());
         assert!(schema.get("global_flags").is_some());
         assert!(schema.get("exit_codes").is_some());
+        assert!(schema.get("errors").is_some());
         assert!(schema.get("commands").is_some());
         assert!(schema.get("notes").is_some());
     }
@@ -481,6 +491,30 @@ mod tests {
         assert_eq!(enums, &[json!("fast"), json!("slow")]);
     }
 
+    #[test]
+    fn schema_errors_array_has_all_kinds() {
+        let schema = generate(&test_cmd());
+        let errors = schema["errors"].as_array().unwrap();
+        assert_eq!(errors.len(), 7);
+
+        let kinds: Vec<&str> = errors.iter().map(|e| e["kind"].as_str().unwrap()).collect();
+        assert!(kinds.contains(&"config"));
+        assert!(kinds.contains(&"auth"));
+        assert!(kinds.contains(&"not_found"));
+        assert!(kinds.contains(&"api"));
+        assert!(kinds.contains(&"conflict"));
+        assert!(kinds.contains(&"timeout"));
+        assert!(kinds.contains(&"other"));
+
+        // Verify retryable fields
+        let api = errors.iter().find(|e| e["kind"] == "api").unwrap();
+        assert_eq!(api["retryable"], true);
+        let timeout = errors.iter().find(|e| e["kind"] == "timeout").unwrap();
+        assert_eq!(timeout["retryable"], true);
+        let config = errors.iter().find(|e| e["kind"] == "config").unwrap();
+        assert_eq!(config["retryable"], false);
+    }
+
     #[test]
     fn schema_handles_nested_subcommands() {
         let schema = generate(&test_cmd());