From 6aa61ac0a9323ede18777949ab6b9af64560343e Mon Sep 17 00:00:00 2001 From: Owen Nelson Date: Tue, 31 Dec 2024 09:52:22 -0800 Subject: [PATCH] CLI: add readme with install instructions The text in this readme is based largely on the one from the old Go CLI. Some sections have been removed since support for the thing being mentioned was not carried forward (e.g. `--data-*` flags and also piping json bodies in which apparently our new clap-based parser doesn't do). Installer instructions are limited to the initial set offered via https://github.com/svix/svix-webhooks/pull/1593 More sections will be added to describe `homebrew`/`cargo` installation once available. --- svix-cli/README.md | 157 +++++++++++++++++++++++++++++++++++++ svix-cli/src/cmds/login.rs | 5 +- svix-cli/src/main.rs | 2 +- svix-cli/src/relay/mod.rs | 5 +- 4 files changed, 165 insertions(+), 4 deletions(-) create mode 100644 svix-cli/README.md diff --git a/svix-cli/README.md b/svix-cli/README.md new file mode 100644 index 000000000..1e0e78160 --- /dev/null +++ b/svix-cli/README.md @@ -0,0 +1,157 @@ +

+ + +

Svix - Webhooks as a service

+ +

+ +# Svix CLI + +[![GitHub release (latest by date)][release-img]][release] + + + +A CLI to interact with the Svix API. + +**With the Svix CLI, you can:** + +- Interact with the Svix CLI +- Validate Webhook payloads + + +## Installation + +### Pre-built executables + +#### Via installer scripts + +Pre-build binaries are available for Linux, macOS via shell script installers. + +``` +curl --proto '=https' --tlsv1.2 -LsSf https://github.com/svix/svix-webhooks/releases/download/v1.44.0/svix-cli-installer.sh | sh +``` + +For Windows users, installation can be done via powershell: + +``` +powershell -ExecutionPolicy ByPass -c "irm https://github.com/svix-onelson/svix-webhooks/releases/download/v1.54.0/svix-cli-installer.ps1 | iex" +``` + +These scripts will install the binaries to `~/.svix/bin` and also add this directory to your `PATH` by default. + +#### Manually + +Additionally, you can select executables to download directly from [our releases page](https://github.com/svix/svix-cli/releases), and use them as is without +having to install anything. + +1. Download and extract the archive for your operating system. +2. Run the `svix-cli` executable from the command line: `./svix-cli help`. + +> ![Note] +> You may need to allow execution by running `chmod +x svix-cli`. + + +You can also put the binaries anywhere in your `PATH` so you can run the command from anywhere without needing to provide its full path. On macOS or Linux you can achieve this by moving the executable to `/usr/local/bin` or `/usr/bin`. + + +## Usage + +Installing the Svix CLI provides access to the `svix` command. + +```sh +svix-cli [command] + +# Run `svix-cli help` for information about the available commands +svix-cli help + +# or add the `--help` flag to any command for a more detailed description and list of flags +svix-cli [command] --help +``` + + +## Using the `listen` command + +The `listen` command creates an on-the-fly publicly accessible URL for use when testing webhooks. + +> ![Note] +> You don't need a Svix account when using the `listen` command. + +The cli then acts as a proxy, forwarding any requests to the given local URL. +This is useful for testing your webhook server locally without having to open a port or +change any NAT configuration on your network. + +Example: + +```sh +svix-cli listen http://localhost:8000/webhook/ +``` + +Output: + +```sh +Webhook Relay is now listening at: +https://play.svix.com/in/c_WKSAVmtHJrohMmgvhF14Mv8FBnM/ + +All requests on this endpoint will be forwarded to your local URL: +http://localhost:8888/ +View logs and debug information at: +https://play.svix.com/view/c_WKSAVmtHJrohMmgvhF14Mv8FBnM/ +To disable logging, run `svix-cli listen --no-logging` +``` + +The above command will return you a unique URL and forward any POST requests it receives +to `http://localhost:8000/webhook/`. + +## Interacting with the Svix Server + +```sh +# Set your Auth Token temporarily via the SVIX_AUTH_TOKEN environment variable +export SVIX_AUTH_TOKEN= +# or to persistently store your auth token in a config file run +svix-cli login # interactively configure your Svix API credentials + +# Create an Application with the name "Demo" +svix-cli application create '{ "name": "demo" }' + +# List Applications +svix-cli application list --limit 2 --iterator some_iterator +``` + +## Commands + +The Svix CLI supports the following commands: +| Command | Description | +| --------------- | ---------------------------------------------------------- | +| login | Interactively configure your Svix API credentials | +| application | List, create & modify applications | +| authentication | Manage authentication tasks such as getting dashboard URLs | +| endpoint | List, create & modify endpoints | +| event-type | List, create & modify event types | +| message | List & create messages | +| message-attempt | List, lookup & resend message attempts | +| signature | Sign or Verify the signature of a webhook message | +| listen | Forward webhook requests a local url | +| integration | List, create & modify integrations | +| open | Quickly open Svix pages in your browser | +| completion | Generate completion script | +| version | Get the version of the Svix CLI | +| help | Help about any command | + + +## Shell Completions + +Shell completion scripts are provided for `bash`, `elvish`, `fish`, `powershell`, and `zsh`. + +To generate a script for your shell type `svix-cli completion `. + +For detailed instructions on configuring completions for your shell run `svix-cli completion --help`. + + +## Documentation + +For a more information, checkout our [API reference](https://docs.svix.com). + + + +[release-img]: https://img.shields.io/github/v/release/svix/svix-cli +[release]: https://github.com/svix/svix-cli/releases diff --git a/svix-cli/src/cmds/login.rs b/svix-cli/src/cmds/login.rs index 8aef74a30..67d79e77c 100644 --- a/svix-cli/src/cmds/login.rs +++ b/svix-cli/src/cmds/login.rs @@ -39,6 +39,9 @@ pub fn prompt() -> Result<()> { "All Set! Your config has been written to `{}`", fp.as_os_str().to_str().unwrap_or_default() ); - println!("Type `svix --help` to print the Svix CLI documentation!"); + println!( + "Type `{} --help` to print the Svix CLI documentation!", + crate::BIN_NAME + ); Ok(()) } diff --git a/svix-cli/src/main.rs b/svix-cli/src/main.rs index d491db575..3107f97d0 100644 --- a/svix-cli/src/main.rs +++ b/svix-cli/src/main.rs @@ -138,7 +138,7 @@ async fn main() -> Result<()> { fn get_client(cfg: &Config) -> Result { let token = cfg.auth_token.clone().ok_or_else(|| { - anyhow::anyhow!("No auth token set. Try running `svix login` to get started.") + anyhow::anyhow!("No auth token set. Try running `{BIN_NAME} login` to get started.") })?; let opts = get_client_options(cfg)?; Ok(svix::api::Svix::new(token, Some(opts))) diff --git a/svix-cli/src/relay/mod.rs b/svix-cli/src/relay/mod.rs index fcb4998a5..f069562af 100644 --- a/svix-cli/src/relay/mod.rs +++ b/svix-cli/src/relay/mod.rs @@ -183,9 +183,10 @@ impl Client { r#" View logs and debug information at: {} - To disable logging, run `svix listen --no-logging` + To disable logging, run `{} listen --no-logging` "#, - view_url(&self.token) + view_url(&self.token), + crate::BIN_NAME, ); } } else {