Buf(1)

📦
version 1.75.0 · 3 versions
, in arch rolling

Buf(1) — the manual page, but make it group chat 💅

Okay bestie, welcome to Buf(1) — no cap, this is the manual for buf-curl. It’s giving “cURL but for RPC,” and honestly? Iconic.

🎀 NAME 🎀

buf-curl — Invoke an RPC endpoint, a la 'cURL'. Periodt.

🦋 SYNOPSIS 🦋

buf curl  [flags]

✨ DESCRIPTION ✨

Okay so this command helps you invoke HTTP RPC endpoints on a server that uses gRPC or Connect. Main character energy fr fr.

By default, server reflection is used, unless the --reflect flag is set to false. Without server reflection, a --schema flag must be provided to indicate the Protobuf schema for the method being invoked. Yes bestie, schema matters. Vibe check your protos.

The only positional argument is the URL of the RPC method to invoke. The name of the method to invoke comes from the last two path components of the URL, which should be the fully-qualified service name and method name, respectively. So like, keep those path bits correct, iykyk.

The URL can use either http or https as the scheme. If http is used then HTTP 1.1 will be used unless the --http2-prior-knowledge flag is set. If https is used then HTTP/2 will be preferred during protocol negotiation and HTTP 1.1 used only if the server does not support HTTP/2. Slay negotiation.

Server reflection, the gRPC protocol, and bidirectional streaming methods all require HTTP/2. So if any of them is used with an http URL, HTTP/2 is used as if the --http2-prior-knowledge flag were set. Not me pointing at the flag like 👀.

The default RPC protocol used will be Connect. To use a different protocol (gRPC or gRPC-Web), use the --protocol flag. Note that the gRPC protocol cannot be used with HTTP 1.1. That’s a hard no, bestie.

The input request is specified via the -d or --data flag. If absent, an empty request is sent. If the flag value starts with an at-sign (@), then the rest of the flag value is interpreted as a filename from which to read the request body. If that filename is just a dash (-), then the request body is read from stdin. The request body is a JSON document that contains the JSON formatted request message. If the RPC method being invoked is a client-streaming method, the request body may consist of multiple JSON values, appended to one another. Multiple JSON documents should usually be separated by whitespace, though this is not strictly required unless the request message type has a custom JSON representation that is not a JSON object. Notes taken, bestie ✍️.

Request metadata (i.e. headers) are defined using -H or --header flags. The flag value is in "name: value" format. But if it starts with an at-sign (@), the rest of the value is interpreted as a filename from which headers are read, each on a separate line. If the filename is just a dash (-), then the headers are read from stdin.

If headers and the request body are both to be read from the same file (or both read from stdin), the file must include headers first, then a blank line, and then the request body. The way that blank line is doing important work? Obsessed.

🍓 Examples 🍓

  1. Issue a unary RPC to a plain-text (i.e. h2c) gRPC server, where the schema for the service is in a Buf module in the current directory, using an empty request message:
$ buf curl --schema . --protocol grpc \
     http://localhost:20202/foo.bar.v1.FooService/DoSomething
  1. Issue an RPC to a Connect server, where the schema comes from the Buf Schema Registry, using a request that is defined as a command-line argument:
$ buf curl --schema buf.build/connectrpc/eliza \
     --data '{"name": "Bob Loblaw"}' \
     https://demo.connectrpc.com/connectrpc.eliza.v1.ElizaService/Introduce
  1. Issue a unary RPC to a server that supports reflection, with verbose output:
$ buf curl --data '{"sentence": "I am not feeling well."}' -v \
     https://demo.connectrpc.com/connectrpc.eliza.v1.ElizaService/Say
  1. Issue a client-streaming RPC to a gRPC-web server that supports reflection, where custom headers and request data are both in a heredoc:
$ buf curl --data @- --header @- --protocol grpcweb \
     https://demo.connectrpc.com/connectrpc.eliza.v1.ElizaService/Converse \
   <<EOM
Custom-Header-1: foo-bar-baz
Authorization: token jas8374hgnkvje9wpkerebncjqol4

{"sentence": "Hi, doc. I feel hungry."}
{"sentence": "What is the answer to life, the universe, and everything?"}
{"sentence": "If you were a fish, what of fish would you be?."}
EOM

Note that server reflection (i.e. use of the --reflect flag) does not work with HTTP 1.1 since the protocol relies on bidirectional streaming. If server reflection is used, the assumed URL for the reflection service is the same as the given URL, but with the last two elements removed and replaced with the service and method name for server reflection. Cute URL surgery, but make it make sense 💅.

If an error occurs that is due to incorrect usage or other unexpected error, this program will return an exit code that is less than 8. If the RPC fails otherwise, this program will return an exit code that is the gRPC code, shifted three bits to the left. Exit-code tea, no cap 🫶.

✨ OPTIONS ✨

okay bestie, this is the flag buffet — every single one, no skipping, no cap. 💅

  • --cacert="" — Path to a PEM-encoded X509 certificate pool file that contains the set of trusted certificate authorities/issuers. If omitted, the system’s default set of trusted certificates are used to verify the server’s certificate. This option is only valid when the URL uses the https scheme. It is not applicable if --insecure or -k flag is used. Default is "".
  • -E, --cert="" — Path to a PEM-encoded X509 certificate file, for using client certificates with TLS. This option is only valid when the URL uses the https scheme. A --key flag must also be present to provide the private key that corresponds to the given certificate. Default is "".
  • --connect-timeout=0 — The time limit, in seconds, for a connection to be established with the server. There is no limit if this flag is not present. Default is 0.
  • -d, --data="" — Request data. This should be zero or more JSON documents, each indicating a request message. For unary RPCs, there should be exactly one JSON document. A special value of @ means to read the data from the file at (the indicated path). If the path is "-" then the request data is read from stdin. If the same file is indicated as used with the request headers flags (--header or -H), the file must contain all headers, then a blank line, and then the request body. It is not allowed to indicate stdin if the schema is expected to be provided via stdin as a file descriptor set or image. Default is "".
  • --emit-defaults[=false] — Emit default values for JSON-encoded responses. Default is false.
  • -H, --header=[] — Request headers to include with the RPC invocation. This flag may be specified more than once to indicate multiple headers. Each flag value should have the form "name: value". A special value of @ means to read headers from the file at (the indicated path). If the path is "-" then headers are read from stdin. If the same file is indicated as used with the request data flag (--data or -d), the file must contain all headers, then a blank line, and then the request body. It is not allowed to indicate stdin if the schema is expected to be provided via stdin as a file descriptor set or image. Default is [].
  • -h, --help[=false] — help for curl (yes, literally, that’s what it says). Default is false.
  • --http2-prior-knowledge[=false] — This flag can be used to indicate that HTTP/2 should be used. Without this, HTTP 1.1 will be used with URLs with an http scheme, and protocol negotiation will be used to choose either HTTP 1.1 or HTTP/2 for URLs with an https scheme. With this flag set, HTTP/2 is always used, even over plain-text. This flag is implied for URLs with an http scheme when server reflection is used, when --protocol is "grpc", or when the method uses bidirectional streaming, since all of these require HTTP/2. Default is false.
  • --http3[=false] — This flag can be used to indicate that HTTP/3 should be used. Without this, HTTP 1.1 will be used with URLs with an http scheme, and protocol negotiation will be used to choose either HTTP 1.1 or HTTP/2 for URLs with an https scheme. With this flag set, HTTP/3 is always used. Default is false.
  • -k, --insecure[=false] — If set, the TLS connection will be insecure and the server’s certificate will NOT be verified. This is generally discouraged. This option is only valid when the URL uses the https scheme. Default is false.
  • --keepalive-time=60 — The duration, in seconds, between TCP keepalive transmissions. Default is 60.
  • --key="" — Path to a PEM-encoded X509 private key file, for using client certificates with TLS. This option is only valid when the URL uses the https scheme. A --cert or -E flag must also be present to provide the certificate and public key that corresponds to the given private key. Default is "".
  • --list-methods[=false] — When set, the command lists supported methods and then exits. If server reflection is used to provide the RPC schema, then the given URL must be a base URL, not including a service or method name. If the schema source is not server reflection, the URL is not used and may be omitted. Default is false.
  • --list-services[=false] — When set, the command lists supported services and then exits. If server reflection is used to provide the RPC schema, then the given URL must be a base URL, not including a service or method name. If the schema source is not server reflection, the URL is not used and may be omitted. Default is false.
  • -n, --netrc[=false] — If true, a file named .netrc in the user’s home directory will be examined to find credentials for the request. The credentials will be sent via a basic authorization header. The command will fail if the file does not have an entry for the hostname in the URL. This flag is ignored if a --user or -u flag is present. This is ignored if a --header or -H flag is provided that sets a header named Authorization. Default is false.
  • --netrc-file="" — This is just like using --netrc or -n, except that the named file is used instead of a file named .netrc in the user’s home directory. This flag cannot be used with the --netrc or -n flag. This is ignored if a --header or -H flag is provided that sets a header named Authorization. Default is "".
  • --no-keepalive[=false] — By default, connections are created using TCP keepalive. If this flag is present, they will be disabled. Default is false.
  • -o, --output="" — Path to output file to create with response data. If absent, response is printed to stdout. Default is "".
  • --protocol="connect" — The RPC protocol to use. This can be one of "grpc", "grpcweb", or "connect". Default is "connect".
  • --reflect[=true] — If true, use server reflection to determine the schema. Default is true.
  • --reflect-header=[] — Request headers to include with reflection requests. This flag may only be used when --reflect is also set. This flag may be specified more than once to indicate multiple headers. Each flag value should have the form "name: value". But a special value of * may be used to indicate that all normal request headers (from --header and -H flags) should also be included with reflection requests. A special value of @ means to read headers from the file at (the indicated path). If the path is "-" then headers are read from stdin. It is not allowed to indicate a file with the same path as used with the request data flag (--data or -d). Furthermore, it is not allowed to indicate stdin if the schema is expected to be provided via stdin as a file descriptor set or image. Default is [].
  • --reflect-protocol="" — The reflection protocol to use for downloading information from the server. This flag may only be used when server reflection is used. By default, this command will try all known reflection protocols from newest to oldest. If this results in a "Not Implemented" error, then older protocols will be used. In practice, this means that "grpc-v1" is tried first, and "grpc-v1alpha" is used if it doesn’t work. If newer reflection protocols are introduced, they may be preferred in the absence of this flag being explicitly set to a specific protocol. The valid values for this flag are "grpc-v1" and "grpc-v1alpha". These correspond to services named "grpc.reflection.v1.ServerReflection" and "grpc.reflection.v1alpha.ServerReflection" respectively. Default is "".
  • --schema=[] — The module to use for the RPC schema. This is necessary if the server does not support server reflection. The format of this argument is the same as for the arguments to other buf sub-commands such as build and generate. It can indicate a directory, a file, a remote module in the Buf Schema Registry, or even standard in ("-") for feeding an image or file descriptor set to the command in a shell pipeline. If multiple schema flags are present, they will be consulted in order to resolve service and type names. Setting this flags implies --reflect=false unless a reflect flag is explicitly present. If both schema and reflect flags are in use, reflection will be used first and the schemas will be consulted in order thereafter if reflection fails to resolve a schema element. Default is [].
  • --servername="" — The server name to use in TLS handshakes (for SNI) if the URL scheme is https. If not specified, the default is the origin host in the URL or the value in a "Host" header if one is provided. Default is "".
  • --unix-socket="" — The path to a unix socket that will be used instead of opening a TCP socket to the host and port indicated in the URL. Default is "".
  • -u, --user="" — The user credentials to send, via a basic authorization header. The value should be in the format "username:password". If the value has no colon, it is assumed to just be the username, in which case you will be prompted to enter a password. This overrides the use of a .netrc file. This is ignored if a --header or -H flag is provided that sets a header named Authorization. Default is "".
  • -A, --user-agent="" — The user agent string to send. This is ignored if a --header or -H flag is provided that sets a header named User-Agent. Default is "".
  • -v, --verbose[=false] — Turn on verbose mode. Default is false.

👑 OPTIONS INHERITED FROM PARENT COMMANDS 👑

these came from the parent command, bestie — still important, still iconic. 🫶

  • --debug[=false] — Turn on debug logging (env BUF_DEBUG). Default is false.
  • --log-format="color" — The log format text, color, json (env BUF_LOG_FORMAT). Default is "color".
  • --timeout=0s — The duration until timing out, setting it to 0 means no timeout (env BUF_TIMEOUT). Default is 0s.

🌈 SEE ALSO 🌈

buf(1)

📜 HISTORY 📜

2026-10-22 Auto generated by spf13/cobra

💖 That’s the page, bestie — source/version Auto generated by spf13/cobra, dated 2026-10-22, for Buf(1). Slay. Periodt. 🎀

📦 where this page comes from