Skip to content

Commit 003468c

Browse files
svix-onelsonsvix-onelson
committed
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 #1593 More sections will be added to describe `homebrew`/`cargo` installation once available.
1 parent 66042cd commit 003468c

File tree

4 files changed

+165
-4
lines changed

4 files changed

+165
-4
lines changed

‎svix-cli/README.md

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
<h1 align="center">
2+
<a href="https://www.svix.com">
3+
<img width="120" src="https://avatars.githubusercontent.com/u/80175132?s=200&v=4" />
4+
<p align="center">Svix - Webhooks as a service</p>
5+
</a>
6+
</h1>
7+
8+
# Svix CLI
9+
10+
[![GitHub release (latest by date)][release-img]][release]
11+
12+
13+
14+
A CLI to interact with the Svix API.
15+
16+
**With the Svix CLI, you can:**
17+
18+
- Interact with the Svix API
19+
- Validate Webhook payloads
20+
21+
22+
## Installation
23+
24+
### Pre-built executables
25+
26+
#### Via installer scripts
27+
28+
Pre-build binaries are available for Linux, macOS via shell script installers.
29+
30+
```
31+
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/svix/svix-webhooks/releases/download/v1.44.0/svix-cli-installer.sh | sh
32+
```
33+
34+
For Windows users, installation can be done via powershell:
35+
36+
```
37+
powershell -ExecutionPolicy ByPass -c "irm https://github.com/svix-onelson/svix-webhooks/releases/download/v1.54.0/svix-cli-installer.ps1 | iex"
38+
```
39+
40+
These scripts will install the binaries to `~/.svix/bin` and also add this directory to your `PATH` by default.
41+
42+
#### Manually
43+
44+
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
45+
having to install anything.
46+
47+
1. Download and extract the archive for your operating system.
48+
2. Run the `svix-cli` executable from the command line: `./svix-cli help`.
49+
50+
> [!NOTE]
51+
> You may need to allow execution by running `chmod +x svix-cli`.
52+
53+
54+
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`.
55+
56+
57+
## Usage
58+
59+
Installing the Svix CLI provides access to the `svix` command.
60+
61+
```sh
62+
svix-cli [command]
63+
64+
# Run `svix-cli help` for information about the available commands
65+
svix-cli help
66+
67+
# or add the `--help` flag to any command for a more detailed description and list of flags
68+
svix-cli [command] --help
69+
```
70+
71+
72+
## Using the `listen` command
73+
74+
The `listen` command creates an on-the-fly publicly accessible URL for use when testing webhooks.
75+
76+
> [!NOTE]
77+
> You don't need a Svix account when using the `listen` command.
78+
79+
The cli then acts as a proxy, forwarding any requests to the given local URL.
80+
This is useful for testing your webhook server locally without having to open a port or
81+
change any NAT configuration on your network.
82+
83+
Example:
84+
85+
```sh
86+
svix-cli listen http://localhost:8000/webhook/
87+
```
88+
89+
Output:
90+
91+
```sh
92+
Webhook Relay is now listening at:
93+
https://play.svix.com/in/c_WKSAVmtHJrohMmgvhF14Mv8FBnM/
94+
95+
All requests on this endpoint will be forwarded to your local URL:
96+
http://localhost:8888/
97+
View logs and debug information at:
98+
https://play.svix.com/view/c_WKSAVmtHJrohMmgvhF14Mv8FBnM/
99+
To disable logging, run `svix-cli listen --no-logging`
100+
```
101+
102+
The above command will return you a unique URL and forward any POST requests it receives
103+
to `http://localhost:8000/webhook/`.
104+
105+
## Interacting with the Svix Server
106+
107+
```sh
108+
# Set your Auth Token temporarily via the SVIX_AUTH_TOKEN environment variable
109+
export SVIX_AUTH_TOKEN=<MY-AUTH-TOKEN>
110+
# or to persistently store your auth token in a config file run
111+
svix-cli login # interactively configure your Svix API credentials
112+
113+
# Create an Application with the name "Demo"
114+
svix-cli application create '{ "name": "demo" }'
115+
116+
# List Applications
117+
svix-cli application list --limit 2 --iterator some_iterator
118+
```
119+
120+
## Commands
121+
122+
The Svix CLI supports the following commands:
123+
| Command | Description |
124+
| --------------- | ---------------------------------------------------------- |
125+
| login | Interactively configure your Svix API credentials |
126+
| application | List, create & modify applications |
127+
| authentication | Manage authentication tasks such as getting dashboard URLs |
128+
| endpoint | List, create & modify endpoints |
129+
| event-type | List, create & modify event types |
130+
| message | List & create messages |
131+
| message-attempt | List, lookup & resend message attempts |
132+
| signature | Sign or Verify the signature of a webhook message |
133+
| listen | Forward webhook requests a local url |
134+
| integration | List, create & modify integrations |
135+
| open | Quickly open Svix pages in your browser |
136+
| completion | Generate completion script |
137+
| version | Get the version of the Svix CLI |
138+
| help | Help about any command |
139+
140+
141+
## Shell Completions
142+
143+
Shell completion scripts are provided for `bash`, `elvish`, `fish`, `powershell`, and `zsh`.
144+
145+
To generate a script for your shell type `svix-cli completion <SHELL NAME>`.
146+
147+
For detailed instructions on configuring completions for your shell run `svix-cli completion --help`.
148+
149+
150+
## Documentation
151+
152+
For a more information, checkout our [API reference](https://docs.svix.com).
153+
154+
155+
156+
[release-img]: https://img.shields.io/github/v/release/svix/svix-cli
157+
[release]: https://github.com/svix/svix-cli/releases

‎svix-cli/src/cmds/login.rs

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,9 @@ pub fn prompt() -> Result<()> {
3939
"All Set! Your config has been written to `{}`",
4040
fp.as_os_str().to_str().unwrap_or_default()
4141
);
42-
println!("Type `svix --help` to print the Svix CLI documentation!");
42+
println!(
43+
"Type `{} --help` to print the Svix CLI documentation!",
44+
crate::BIN_NAME
45+
);
4346
Ok(())
4447
}

‎svix-cli/src/main.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -138,7 +138,7 @@ async fn main() -> Result<()> {
138138

139139
fn get_client(cfg: &Config) -> Result<svix::api::Svix> {
140140
let token = cfg.auth_token.clone().ok_or_else(|| {
141-
anyhow::anyhow!("No auth token set. Try running `svix login` to get started.")
141+
anyhow::anyhow!("No auth token set. Try running `{BIN_NAME} login` to get started.")
142142
})?;
143143
let opts = get_client_options(cfg)?;
144144
Ok(svix::api::Svix::new(token, Some(opts)))

‎svix-cli/src/relay/mod.rs

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -183,9 +183,10 @@ impl Client {
183183
r#"
184184
View logs and debug information at:
185185
{}
186-
To disable logging, run `svix listen --no-logging`
186+
To disable logging, run `{} listen --no-logging`
187187
"#,
188-
view_url(&self.token)
188+
view_url(&self.token),
189+
crate::BIN_NAME,
189190
);
190191
}
191192
} else {

0 commit comments

Comments
 (0)