|
1 | 1 | # PagerTree CLI |
2 | 2 |
|
3 | | -A command-line interface (CLI) tool for interacting with the PagerTree API. This tool allows users to manage alerts and other resources in PagerTree directly from the terminal. Built with Python and `click`, it supports nested commands, pagination, and table-formatted output. |
| 3 | + |
| 4 | + |
| 5 | + |
| 6 | +The PagerTree CLI is a powerful command-line tool for managing incidents, alerts, and on-call schedules in [PagerTree](https://pagertree.com), a modern incident management platform. Designed for sysadmins, DevOps engineers, and IT teams, it lets you interact with PagerTree’s API directly from your terminal, streamlining workflows and automating tasks. |
4 | 7 |
|
5 | 8 | ## Features |
6 | | -- Manage PagerTree objects such as alerts, teams, broadcasts, and users. |
7 | | -- Pagination support with `--limit`, `--offset`, and `--search` options. |
8 | | -- Pretty table output using `tabulate`. |
9 | | -- Environment variable configuration with `.env` file support. |
10 | | -- Support for configuration files `config.ini`. |
| 9 | +- Create, view, and manage alerts, teams, broadcasts, and users. |
| 10 | +- Filter and search resources with flexible options. |
| 11 | +- View results in clean, table-formatted output. |
| 12 | +- Configure via environment variables or a simple config file. |
| 13 | +- Cross-platform support for macOS, Linux, and Windows. |
11 | 14 |
|
12 | | -## Usage |
13 | | -```bash |
14 | | -pagertree [OPTIONS] COMMAND [ARGS...] |
15 | | -``` |
| 15 | +## Installation |
| 16 | + |
| 17 | +### Prerequisites |
| 18 | +- A PagerTree account and API key (get one from the [PagerTree User Settings Page](https://app.pagertree.com/user/settings)). |
| 19 | +- Python 3.8+ (optional, only if not using pre-built binaries). |
| 20 | + |
| 21 | +### Option 1: Install Pre-Built Binaries (Recommended) |
| 22 | +1. Visit the [releases page](https://github.com/PagerTree/pager_tree-cli/releases). |
| 23 | +2. Download the binary for your operating system (e.g., `pagertree`, `pagertree.exe`). |
| 24 | +3. Make the binary executable (Linux/macOS): |
| 25 | + ```bash |
| 26 | + chmod +x pagertree |
| 27 | + ``` |
| 28 | +4. Move the binary to a directory in your PATH (e.g., `/usr/local/bin`): |
| 29 | + ```bash |
| 30 | + mv pagertree /usr/local/bin/ |
| 31 | + ``` |
| 32 | +5. Verify installation: |
| 33 | + ```bash |
| 34 | + pagertree --help |
| 35 | + ``` |
16 | 36 |
|
17 | | -Run `pagertree --help` to see the list of available commands and options. |
18 | | - |
19 | | -### Example Usage |
20 | | -- List all alerts: |
21 | | - ```bash |
22 | | - pagertree alerts list |
23 | | - ``` |
24 | | - OR |
25 | | - ```bash |
26 | | - pagertree alerts list --limit 10 --offset 0 |
27 | | - ``` |
28 | | - OR |
29 | | - ```bash |
30 | | - pagertree alerts list --search "NEEDLE IN THE HAYSTACK" |
31 | | - ``` |
32 | | -- Create a new alert: |
33 | | - ```bash |
34 | | - pagertree alerts create --title "Out of Memory" --alias "oom" --team-ids "01JT13C98M186XA3QTRFC250MT" |
35 | | - ``` |
36 | | -- Show details of a specific alert: |
37 | | - ```bash |
38 | | - pagertree alerts show "01JT13CYDAMAJDM0G8HR1X8BMY" |
39 | | - ``` |
40 | | - OR |
41 | | - ```bash |
42 | | - pagertree alerts show --alias "oom" |
43 | | - ``` |
44 | | -- List all teams: |
45 | | - ```bash |
46 | | - pagertree teams list |
47 | | - ``` |
48 | | -- List current on-call users for a specific team: |
49 | | - ```bash |
50 | | - pagertree teams current-oncall "01JT13C98M186XA3QTRFC250MT" |
51 | | - ``` |
52 | | -- Run a command with a specific configuration file: |
53 | | - ```bash |
54 | | - pagertree --config config.ini alerts list |
55 | | - ``` |
56 | | - OR |
57 | | - ```bash |
58 | | - PAGERTREE_CONFIG=config.ini pagertree alerts list |
59 | | - ``` |
60 | | -- Run a command with a specific environment variable: |
61 | | - ```bash |
62 | | - PAGERTREE_API_KEY=your_api_key pagertree alerts list |
63 | | - ``` |
64 | | - |
65 | | -## Pre-Built Binaries |
66 | | -Pre-built binaries for various platforms are available in the [releases](https://github.com/PagerTree/pager_tree-cli/releases) section. You can download the appropriate binary for your operating system and architecture. |
67 | | - |
68 | | -### Source Code Installation & Development |
| 37 | +### Option 2: Install via Python |
69 | 38 | 1. Clone the repository: |
70 | 39 | ```bash |
71 | | - git clone |
| 40 | + git clone https://github.com/PagerTree/pager_tree-cli.git |
72 | 41 | cd pager_tree-cli |
73 | | - ``` |
74 | | -2. Install dependencies: |
75 | | - ```bash |
76 | | - source venv/bin/activate |
77 | | - pip install -r requirements.txt |
78 | | - ``` |
79 | | -3. Make the script executable: |
80 | | - ```bash |
81 | | - chmod +x pagertree.py |
82 | | - ``` |
83 | | -4. Run the script: |
84 | | - ```bash |
85 | | - python ./pagertree.py |
86 | | - ``` |
| 42 | + ``` |
| 43 | +2. Set up a virtual environment and install dependencies: |
| 44 | + ```bash |
| 45 | + python -m venv venv |
| 46 | + source venv/bin/activate # On Windows: venv\Scripts\activate |
| 47 | + pip install -r requirements.txt |
| 48 | + ``` |
| 49 | +3. Run the CLI: |
| 50 | + ```bash |
| 51 | + python pagertree.py --help |
| 52 | + ``` |
| 53 | + |
| 54 | +## Configuration |
| 55 | + |
| 56 | +To use the PagerTree CLI, you need to configure your PagerTree API key. |
| 57 | + |
| 58 | +### Option 1: Environment Variable |
| 59 | +Set the API key as an environment variable: |
| 60 | +```bash |
| 61 | +export PAGERTREE_API_KEY=your_api_key_here |
| 62 | +``` |
| 63 | +Add it to your shell profile (e.g., `~/.bashrc`, `~/.zshrc`) for persistence. |
| 64 | + |
| 65 | +### Option 2: Configuration File |
| 66 | +Create a `config.ini` file: |
| 67 | +```ini |
| 68 | +[DEFAULT] |
| 69 | +API_KEY = your_api_key_here |
| 70 | +``` |
| 71 | +Specify the config file when running commands: |
| 72 | +```bash |
| 73 | +pagertree --config config.ini alerts list |
| 74 | +``` |
| 75 | + |
| 76 | +### Option 3: .env File |
| 77 | +Create a `.env` file in the working directory: |
| 78 | +```env |
| 79 | +PAGERTREE_API_KEY=your_api_key_here |
| 80 | +``` |
| 81 | +The CLI automatically loads the `.env` file. |
| 82 | + |
| 83 | +## Usage |
| 84 | + |
| 85 | +Run `pagertree --help` to see all available commands and options. |
| 86 | + |
| 87 | +### Common Commands |
| 88 | +| Command | Description | |
| 89 | +|---------|-------------| |
| 90 | +| `pagertree alerts list` | List all alerts. | |
| 91 | +| `pagertree alerts create --title "Out of Memory" --team-ids "01JT13C98M186XA3QTRFC250MT"` | Create a new alert. | |
| 92 | +| `pagertree alerts show "01JT13CYDAMAJDM0G8HR1X8BMY"` | Show details of an alert. | |
| 93 | +| `pagertree teams list` | List all teams. | |
| 94 | +| `pagertree teams current-oncall "01JT13C98M186XA3QTRFC250MT"` | List current on-call users for a team. | |
| 95 | + |
| 96 | +### Advanced Options |
| 97 | +- Filter alerts with search: |
| 98 | + ```bash |
| 99 | + pagertree alerts list --search "NEEDLE IN THE HAYSTACK" |
| 100 | + ``` |
| 101 | +- Paginate results: |
| 102 | + ```bash |
| 103 | + pagertree alerts list --limit 10 --offset 0 |
| 104 | + ``` |
| 105 | +- Use an alias for alerts: |
| 106 | + ```bash |
| 107 | + pagertree alerts show --alias "oom" |
| 108 | + ``` |
| 109 | + |
| 110 | +For more commands, see the [PagerTree CLI Documentation](https://pagertree.com/docs/cli). |
| 111 | + |
| 112 | +## Support |
| 113 | + |
| 114 | +- **Issues**: Report bugs or request features on the [GitHub Issues page](https://github.com/PagerTree/pager_tree-cli/issues). |
| 115 | +- **Documentation**: Visit [PagerTree CLI Documentation](https://pagertree.com/docs/cli). |
| 116 | +- **Contact**: Email support@pagertree.com for assistance. |
| 117 | + |
| 118 | +## License |
| 119 | + |
| 120 | +This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. |
0 commit comments