Skip to content

Commit

Permalink
docs: revise readme (#78)
Browse files Browse the repository at this point in the history 
* Editing the readme to improve clarity, consistency, and correctness

* fix structure, consistency, spelling issues

* improve example readibility

* incorporate feedback

* integrations page

---------

Co-authored-by: Sarah Mischinger <sarah@codingwriter.com>
Co-authored-by: Dmitriy Akulov <dakulovgr@gmail.com>
  • Loading branch information
@inventarSarah @jimaek
3 people committed Nov 23, 2023
1 parent 5d140a8 commit 92883bc
Showing 1 changed file with 51 additions and 30 deletions.
81 changes: 51 additions & 30 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,22 @@
<h1 align="center"> <a href="https://www.jsdelivr.com/globalping"><img width="28" alt="Globalping icon" src="https://user-images.githubusercontent.com/1834071/216975126-01529980-a87e-478c-8ab3-bf7d927a1986.png"></a> Globalping CLI </h1>

<p align="center">Access a global network of probes without leaving your console. Powered by the Globalping community!</p>
<p align="center">Access a global network of probes without leaving your console. Benchmark your internet infrastructure, automate uptime and latency monitoring with scripts, or optimize your anycast network – from any location and free of charge. Powered by the Globalping community!</p>

<p align="center"><img width="80%" src="https://user-images.githubusercontent.com/1834071/217010016-9da38f12-906a-47cf-adca-18017588efe5.png">
</p>

- The official command-line interface for the [Globalping](https://github.com/jsdelivr/globalping) network.
## Key features
- The official command-line interface for the [Globalping](https://github.com/jsdelivr/globalping) network
- Run networking commands from any location in the world
- Supported commands: ping, mtr, traceroute, dns resolve, HTTP
- Includes detailed timings and latency metrics with every test
- Real-time results right in your command line
- Human friendly format and output
- Cross-platform. Linux, MacOS, Windows are all supported
- Real-time results for all supported commands: ping, mtr, traceroute, DNS resolve, HTTP
- Includes detailed timings and latency metrics for every test
- Human-friendly format and output
- Supports Linux, MacOS, and Windows
- Auto-updated via all automated installation methods
- [Check our website for online tools, our Slack app and more!](https://www.jsdelivr.com/globalping)
- Explore additional [Globalping integrations](https://www.jsdelivr.com/globalping/integrations), including our online tools, Slack app, and more

## Installation - Quick start

Simply run these commands to install the repo and CLI! This way you will get all future updates by simply running an update using your package manager.
## Installation
Install the repository and Globalping CLI using the relevant package manager command from below. This way, you can get future updates by simply running an update with your package manager.

### Ubuntu/Debian (deb)

Expand Down Expand Up @@ -55,17 +54,24 @@ winget install globalping
```

### Binary installation
Every new release is compiled into binaries ready to run on most operating systems and provided as assets on GitHub. You can download and execute these binaries directly on your system.

Every new release is compiled into binaries ready to run on most operating systems and attached as assets on GitHub. You can download and run the binaries directly on your system, but note that you will have to repeat this process for every new release. [Explore the available versions](https://github.com/jsdelivr/globalping-cli/releases).
> [!IMPORTANT]
> Opting for this installation method means you'll have to repeat this manual process to update the CLI to a newer release!
[Explore the available versions](https://github.com/jsdelivr/globalping-cli/releases).

## Getting Started with Globalping CLI
## Updating
If you've installed the Globalping CLI via a package manager, you only need to run the manager's update command to get the latest Globalping CLI version.

Once the Globalping CLI is installed, you can verify that it is working by running:
## Getting started with Globalping CLI

```bash
globalping --help
After installing, verify the Globalping CLI is working by running:

`globalping --help`

The result shows how to use the CLI and which commands and flags are available:
```bash
Globalping is a platform that allows anyone to run networking commands such as ping, traceroute, dig and mtr on probes distributed all around the world.
The CLI tool allows you to interact with the API in a simple and human-friendly way to debug networking issues like anycast routing and script automated tests and benchmarks.

Expand Down Expand Up @@ -96,13 +102,11 @@ Flags:
Use "globalping [command] --help" for more information about a command.
```

#### Next we recommend [reading our best practices](https://github.com/jsdelivr/globalping#best-practices-and-tips) to learn more about how to effectively select locations.

### Run your first test

The following command will show a real-time result of ping from probes that have the parameters Comcast and Seattle.
You can use the + symbol as a filter to select probes more precisely.
### Run your first tests
Globalping relies on a community-hosted probe network, enabling you to run network tests from any location with an active probe. The following examples show you through some tests, exploring how to define locations, set limits, and use some command flags.

#### Filter locations
For example, if you want to run ping from a probe in Seattle that is also part of the Comcast network, run the following:
```bash
globalping ping google.com from Comcast+Seattle
> NA, US, (WA), Seattle, ASN:7922, Comcast Cable Communications, LLC
Expand All @@ -115,11 +119,13 @@ PING (142.250.217.78) 56(84) bytes of data.
3 packets transmitted, 3 received, 0% packet loss, time 402ms
rtt min/avg/max/mdev = 13.985/14.779/15.886/0.807 ms
```
You can use the `+` symbol as a filter to select the desired location of the probes more precisely.

To select multiple locations you can use a comma as a delimiter. You can mix and match the location types without issues.
We also set a limit of 4 probes to get 1 answer per location, otherwise the default limit of 1 would result in a random result from one of the four locations.
> [!TIP]
> You can mix and match any location type, including countries, continents, cities, US states, regions, ASNs, ISP names, eyeball or data center tags, and cloud region names.
Last we use the `--latency` parameter to only get the summary latency data instead of the full raw ping output.
#### Define multiple locations and basic flags
With the following command, we execute four ping commands at four different locations and obtain the summarized latency metrics for each test as a result:

```bash
globalping ping google.com from Amazon,Germany,USA,Dallas --limit 4 --latency
Expand All @@ -143,9 +149,19 @@ Min: 1.579 ms
Max: 1.588 ms
Avg: 1.584 ms
```
You can select multiple locations for running a command by using a comma `,` as a delimiter. When doing so, make sure to also specify the number of tests to run with the `--limit` flag.
For example, to run ping from four different locations (as we did in the example above), add `--limit 4` to make sure you get one test result per location. Otherwise, the default limit of 1 will be selected, resulting in a random result from one of the four locations.

Finally, you can use the `--latency` parameter to only get the summarized latency data instead of the full raw output.

> [!TIP]
> We recommend reading our [tips and best practices](https://github.com/jsdelivr/globalping#best-practices-and-tips) to learn more about defining locations effectively!
The `--share` parameter will add a link to end of any test to view the results online.
Note that these links expire after a few weeks depending on the type of user. GitHub Sponsors get their tests stored for longer.
#### Share results online
Include a link at the bottom of your results using the `--share` flag to view and share the test results online.

> [!IMPORTANT]
> Shareable links and the respective saved measurement results expire after a few weeks, depending on the user type. GitHub Sponsors, for example, enjoy extended result storage.
```bash
globalping dns google.com from gcp-asia-south1 --share
Expand All @@ -171,10 +187,15 @@ google.com. 300 IN A 142.250.183.206
> View the results online: https://www.jsdelivr.com/globalping?measurement=xrfXUEAOGfzwfHFz
```
Most commands have their own unique parameters, explore them to run and automate your network tests in powerful ways.
#### Learn about available flags
Most commands have shared and unique flags. We recommend that you familiarize yourself with these so that you can run and automate your network tests in powerful ways.
Simply execute the command you want to learn more about with the `--help` flag:
If you get stuck or want to provide your feedback please open a new issue.
`globalping [command] --help`
## Development setup
## Support and Feedback
If you are stuck or want to give us your feedback, please [open a new issue](https://github.com/jsdelivr/globalping-cli/issues).
## Development
Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for more information.

0 comments on commit 92883bc

Please sign in to comment.