Skip to content

Make cli output json #78

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tnull merged 1 commit into from
Dec 15, 2025
Merged

Make cli output json #78

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 3 additions & 2 deletions ldk-server-cli/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ version = "0.1.0"
edition = "2021"

[dependencies]
ldk-server-client = { path = "../ldk-server-client" }
ldk-server-client = { path = "../ldk-server-client", features = ["serde"] }
clap = { version = "4.0.5", default-features = false, features = ["derive", "std", "error-context", "suggestions", "help"] }
tokio = { version = "1.38.0", default-features = false, features = ["rt-multi-thread", "macros"] }
prost = { version = "0.11.6", default-features = false}
Copy link
Collaborator

@tnull tnull Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, could be debated if we want to deviate from the 'protobuf-over-HTTP' approach, but I'm not sure if we should introduce all the boilerplate to support yet another encoding of the same request/response data?

Copy link
Collaborator Author

@benthecarman benthecarman Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to be clear, this dep was unused here, that's why i removed it, we get it from ldk-server-client.

but yeah it does suck to have a separate encoding but its pretty important to have your cli output be human and machine readable

Copy link
Collaborator

@tnull tnull Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to be clear, this dep was unused here, that's why i removed it, we get it from ldk-server-client.

Ah, gotcha.

but yeah it does suck to have a separate encoding but its pretty important to have your cli output be human and machine readable

Isn't machine readability mostly important if the cli is considered the main API to interact with a service? We however went out of our way to ensure we provide a 'proper' API via protobufs and even provide a ready-to-go client library to interact with it programatically. I think we def. want to discourage parsing cli stdout/stdin to interact with the service?

Copy link
Collaborator Author

@benthecarman benthecarman Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't machine readability mostly important if the cli is considered the main API to interact with a service? We however went out of our way to ensure we provide a 'proper' API via protobufs and even provide a ready-to-go client library to interact with it programatically. I think we def. want to discourage parsing cli stdout/stdin to interact with the service?

Yeah I agree we don't want the cli to be the primary api, but I still think machine readability is important. I often pipe bitcoind and lnd cli commands though jq to more easily read stuff or to do quick computations. This is often useful as well for chaining commands together

Copy link
Collaborator

@tnull tnull Dec 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, but I have to say I still hate the idea of taking on the maintainance burden of almost 1000 LoC just to be able to print as valid JSON. If that's important we should really find another way to do it rather than just having an agent spit out a lot of boilerplate that nobody ever wants to read/maintain.

Turns out it's really easy to add serde/JSON support on the generated protos by just adding:

diff --git a/ldk-server-protos/Cargo.toml b/ldk-server-protos/Cargo.toml
index 5d16484..65894e2 100644
--- a/ldk-server-protos/Cargo.toml
+++ b/ldk-server-protos/Cargo.toml
@@ -7,6 +7,8 @@ build = "build.rs"

 [dependencies]
 prost = { version = "0.11.6", default-features = false, features = ["std", "prost-derive"] }
+serde = { version = "1.0", features = ["derive"] }
+bytes = { version = "1", features = ["serde"] }

 [target.'cfg(genproto)'.build-dependencies]
 prost-build = { version = "0.11.6" , default-features = false}
diff --git a/ldk-server-protos/build.rs b/ldk-server-protos/build.rs
index 76eb77a..ac5d0ce 100644
--- a/ldk-server-protos/build.rs
+++ b/ldk-server-protos/build.rs
@@ -13,6 +13,8 @@ fn main() {
 #[cfg(genproto)]
 fn generate_protos() {
        prost_build::Config::new()
+               .type_attribute(".", "#[derive(serde::Serialize, serde::Deserialize)]")
+               .type_attribute(".", "#[serde(rename_all = \"snake_case\")]")
                .bytes(&["."])
                .compile_protos(
                        &[

Also see tokio-rs/prost#75 and https://protobuf.dev/programming-guides/proto3/#json

From there we could consider hiding the additional attributes behind a serde or json feature, so that they are only used by/exposed to the cli, avoiding any confusion which serialization/deserialization you want to use in other contexts.

Copy link
Collaborator Author

@benthecarman benthecarman Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay good find, much easier

serde = "1.0"
serde_json = "1.0"
81 changes: 55 additions & 26 deletions ldk-server-cli/src/main.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,20 @@ use ldk_server_client::error::LdkServerErrorCode::{
AuthError, InternalError, InternalServerError, InvalidRequestError, LightningError,
};
use ldk_server_client::ldk_server_protos::api::{
Bolt11ReceiveRequest, Bolt11SendRequest, Bolt12ReceiveRequest, Bolt12SendRequest,
CloseChannelRequest, ForceCloseChannelRequest, GetBalancesRequest, GetNodeInfoRequest,
ListChannelsRequest, ListPaymentsRequest, OnchainReceiveRequest, OnchainSendRequest,
OpenChannelRequest, SpliceInRequest, SpliceOutRequest, UpdateChannelConfigRequest,
Bolt11ReceiveRequest, Bolt11ReceiveResponse, Bolt11SendRequest, Bolt11SendResponse,
Bolt12ReceiveRequest, Bolt12ReceiveResponse, Bolt12SendRequest, Bolt12SendResponse,
CloseChannelRequest, CloseChannelResponse, ForceCloseChannelRequest, ForceCloseChannelResponse,
GetBalancesRequest, GetBalancesResponse, GetNodeInfoRequest, GetNodeInfoResponse,
ListChannelsRequest, ListChannelsResponse, ListPaymentsRequest, ListPaymentsResponse,
OnchainReceiveRequest, OnchainReceiveResponse, OnchainSendRequest, OnchainSendResponse,
OpenChannelRequest, OpenChannelResponse, SpliceInRequest, SpliceInResponse, SpliceOutRequest,
SpliceOutResponse, UpdateChannelConfigRequest, UpdateChannelConfigResponse,
};
use ldk_server_client::ldk_server_protos::types::RouteParametersConfig;
use ldk_server_client::ldk_server_protos::types::{
bolt11_invoice_description, channel_config, Bolt11InvoiceDescription, ChannelConfig, PageToken,
Payment,
bolt11_invoice_description, Bolt11InvoiceDescription, ChannelConfig, PageToken, Payment,
RouteParametersConfig,
};
use std::fmt::Debug;
use serde::Serialize;

// Having these default values as constants in the Proto file and
// importing/reusing them here might be better, but Proto3 removed
Expand Down Expand Up @@ -199,16 +202,22 @@ async fn main() {

match cli.command {
Commands::GetNodeInfo => {
handle_response_result(client.get_node_info(GetNodeInfoRequest {}).await);
handle_response_result::<_, GetNodeInfoResponse>(
client.get_node_info(GetNodeInfoRequest {}).await,
);
},
Commands::GetBalances => {
handle_response_result(client.get_balances(GetBalancesRequest {}).await);
handle_response_result::<_, GetBalancesResponse>(
client.get_balances(GetBalancesRequest {}).await,
);
},
Commands::OnchainReceive => {
handle_response_result(client.onchain_receive(OnchainReceiveRequest {}).await);
handle_response_result::<_, OnchainReceiveResponse>(
client.onchain_receive(OnchainReceiveRequest {}).await,
);
},
Commands::OnchainSend { address, amount_sats, send_all, fee_rate_sat_per_vb } => {
handle_response_result(
handle_response_result::<_, OnchainSendResponse>(
client
.onchain_send(OnchainSendRequest {
address,
Expand Down Expand Up @@ -239,7 +248,9 @@ async fn main() {
let request =
Bolt11ReceiveRequest { description: invoice_description, expiry_secs, amount_msat };

handle_response_result(client.bolt11_receive(request).await);
handle_response_result::<_, Bolt11ReceiveResponse>(
client.bolt11_receive(request).await,
);
},
Commands::Bolt11Send {
invoice,
Expand All @@ -257,7 +268,7 @@ async fn main() {
max_channel_saturation_power_of_half: max_channel_saturation_power_of_half
.unwrap_or(DEFAULT_MAX_CHANNEL_SATURATION_POWER_OF_HALF),
};
handle_response_result(
handle_response_result::<_, Bolt11SendResponse>(
client
.bolt11_send(Bolt11SendRequest {
invoice,
Expand All @@ -268,7 +279,7 @@ async fn main() {
);
},
Commands::Bolt12Receive { description, amount_msat, expiry_secs, quantity } => {
handle_response_result(
handle_response_result::<_, Bolt12ReceiveResponse>(
client
.bolt12_receive(Bolt12ReceiveRequest {
description,
Expand Down Expand Up @@ -298,7 +309,7 @@ async fn main() {
.unwrap_or(DEFAULT_MAX_CHANNEL_SATURATION_POWER_OF_HALF),
};

handle_response_result(
handle_response_result::<_, Bolt12SendResponse>(
client
.bolt12_send(Bolt12SendRequest {
offer,
Expand All @@ -311,7 +322,7 @@ async fn main() {
);
},
Commands::CloseChannel { user_channel_id, counterparty_node_id } => {
handle_response_result(
handle_response_result::<_, CloseChannelResponse>(
client
.close_channel(CloseChannelRequest { user_channel_id, counterparty_node_id })
.await,
Expand All @@ -322,7 +333,7 @@ async fn main() {
counterparty_node_id,
force_close_reason,
} => {
handle_response_result(
handle_response_result::<_, ForceCloseChannelResponse>(
client
.force_close_channel(ForceCloseChannelRequest {
user_channel_id,
Expand All @@ -348,7 +359,7 @@ async fn main() {
cltv_expiry_delta,
);

handle_response_result(
handle_response_result::<_, OpenChannelResponse>(
client
.open_channel(OpenChannelRequest {
node_pubkey,
Expand All @@ -362,7 +373,7 @@ async fn main() {
);
},
Commands::SpliceIn { user_channel_id, counterparty_node_id, splice_amount_sats } => {
handle_response_result(
handle_response_result::<_, SpliceInResponse>(
client
.splice_in(SpliceInRequest {
user_channel_id,
Expand All @@ -378,7 +389,7 @@ async fn main() {
address,
splice_amount_sats,
} => {
handle_response_result(
handle_response_result::<_, SpliceOutResponse>(
client
.splice_out(SpliceOutRequest {
user_channel_id,
Expand All @@ -390,10 +401,17 @@ async fn main() {
);
},
Commands::ListChannels => {
handle_response_result(client.list_channels(ListChannelsRequest {}).await);
handle_response_result::<_, ListChannelsResponse>(
client.list_channels(ListChannelsRequest {}).await,
);
},
Commands::ListPayments { number_of_payments } => {
handle_response_result(list_n_payments(client, number_of_payments).await);
handle_response_result::<_, ListPaymentsResponse>(
list_n_payments(client, number_of_payments)
.await
// todo: handle pagination properly
.map(|payments| ListPaymentsResponse { payments, next_page_token: None }),
);
},
Commands::UpdateChannelConfig {
user_channel_id,
Expand All @@ -411,7 +429,7 @@ async fn main() {
max_dust_htlc_exposure: None,
};

handle_response_result(
handle_response_result::<_, UpdateChannelConfigResponse>(
client
.update_channel_config(UpdateChannelConfigRequest {
user_channel_id,
Expand Down Expand Up @@ -466,10 +484,21 @@ async fn list_n_payments(
Ok(payments)
}

fn handle_response_result<Rs: Debug>(response: Result<Rs, LdkServerError>) {
fn handle_response_result<Rs, Js>(response: Result<Rs, LdkServerError>)
where
Rs: Into<Js>,
Js: Serialize + std::fmt::Debug,
{
match response {
Ok(response) => {
println!("Success: {:?}", response);
let json_response: Js = response.into();
match serde_json::to_string_pretty(&json_response) {
Ok(json) => println!("{json}"),
Err(e) => {
eprintln!("Error serializing response ({json_response:?}) to JSON: {e}");
std::process::exit(1);
},
}
},
Err(e) => {
handle_error(e);
Expand Down
4 changes: 4 additions & 0 deletions ldk-server-client/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@ name = "ldk-server-client"
version = "0.1.0"
edition = "2021"

[features]
default = []
serde = ["ldk-server-protos/serde"]

[dependencies]
ldk-server-protos = { path = "../ldk-server-protos" }
reqwest = { version = "0.11.13", default-features = false, features = ["rustls-tls"] }
Expand Down
8 changes: 7 additions & 1 deletion ldk-server-protos/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,14 @@ edition = "2021"

build = "build.rs"

[features]
default = []
serde = ["dep:serde", "dep:bytes"]

[dependencies]
prost = { version = "0.11.6", default-features = false, features = ["std", "prost-derive"] }
serde = { version = "1.0", features = ["derive"], optional = true }
bytes = { version = "1", features = ["serde"], optional = true }

[target.'cfg(genproto)'.build-dependencies]
prost-build = { version = "0.11.6" , default-features = false}
prost-build = { version = "0.11.6", default-features = false }
5 changes: 5 additions & 0 deletions ldk-server-protos/build.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,11 @@ fn main() {
fn generate_protos() {
prost_build::Config::new()
.bytes(&["."])
.type_attribute(
".",
"#[cfg_attr(feature = \"serde\", derive(serde::Serialize, serde::Deserialize))]",
)
.type_attribute(".", "#[cfg_attr(feature = \"serde\", serde(rename_all = \"snake_case\"))]")
.compile_protos(
&[
"src/proto/api.proto",
Expand Down
Loading