Skip to content

Commit 245d199

Browse files
francescobiancofrancescobianco
committed
Updated at mer 11 feb 2026, 16:29:48, CET
1 parent 58887ff commit 245d199

2 files changed

Lines changed: 364 additions & 29 deletions

File tree

‎README.md‎

Lines changed: 158 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,68 @@
1-
# openapi-cli
1+
<div align="center">
2+
<a href="https://openapi.com/">
3+
<img alt="Openapi CLI" src=".github/assets/repo-header-a3.png" >
4+
</a>
25

6+
<h1>Openapi® CLI</h1>
7+
<h4>The command-line interface to interact with <a href="https://openapi.com/">Openapi®</a> APIs directly from your terminal</h4>
38

4-
# openapi CLI - Usage Guide
9+
[![Build Status](https://github.com/openapi/openapi-cli/actions/workflows/rust.yml/badge.svg)](https://github.com/openapi/openapi-cli/actions/workflows/rust.yml)
10+
[![License](https://img.shields.io/github/license/openapi/openapi-cli)](LICENSE)
11+
[![Rust Version](https://img.shields.io/badge/rust-2024_edition-orange.svg)](https://www.rust-lang.org/)
12+
</div>
13+
14+
## Overview
15+
16+
A command-line client for the APIs available at [Openapi](https://openapi.com).
17+
It provides direct terminal access to the Openapi Marketplace, including token management, scope aliases, and sandbox support.
18+
With this CLI you can quickly interact with hundreds of certified APIs and accelerate your digital transformation projects.
19+
20+
## Pre-requisites
21+
22+
Before using the Openapi CLI, you will need an account at [Openapi](https://console.openapi.com/) and an API key to the sandbox and/or production environment.
23+
24+
## What you can do
25+
26+
With the Openapi CLI, you can easily interact with a variety of services in the Openapi Marketplace. For example, you can:
27+
28+
- Send SMS messages with delivery reports and custom sender IDs
29+
- Process bills and payments in real time via API
30+
- Send electronic invoices securely to the Italian Revenue Agency
31+
- Generate PDFs from HTML content, including JavaScript rendering
32+
- Manage certified emails and legal communications via Italian Legalmail
33+
- Query company data, risk reports, automotive records, and more
34+
35+
For a complete list of all available services, check out the [Openapi Marketplace](https://console.openapi.com/).
36+
37+
## Installation
38+
39+
### From source
40+
41+
```bash
42+
git clone https://github.com/openapi/openapi-cli.git
43+
cd openapi-cli
44+
cargo install --path .
45+
```
46+
47+
Or using make:
48+
49+
```bash
50+
make install
51+
```
52+
53+
The binary `openapi` will be installed in `~/.cargo/bin/`.
54+
55+
### Build without installing
56+
57+
```bash
58+
cargo build --release
59+
```
60+
61+
The binary will be available at `target/release/openapi`.
562

663
## Configuration
764

8-
The CLI uses two sets of credentials:
65+
The CLI uses two sets of environment variables depending on the type of command.
966

1067
### OAuth credentials (for token management)
1168

@@ -14,27 +71,27 @@ Used by `openapi token` commands. These are your Openapi.it account credentials
1471
```bash
1572
export OPENAPI_USERNAME="your-username"
1673
export OPENAPI_KEY="your-api-key"
17-
export OPENAPI_SANDBOX_KEY="your-sandbox-key" # optional
74+
export OPENAPI_SANDBOX_KEY="your-sandbox-key" # optional
1875
```
1976

2077
### Bearer tokens (for service API commands)
2178

22-
Used by all other commands (`sms`, `company`, `risk`, etc.). These are tokens generated via `openapi token create`.
79+
Used by all service commands (`sms`, `company`, `risk`, etc.). These are tokens generated via `openapi token create`.
2380

2481
```bash
2582
export OPENAPI_TOKEN="your-bearer-token"
26-
export OPENAPI_SANDBOX_TOKEN="your-sandbox-token" # optional
83+
export OPENAPI_SANDBOX_TOKEN="your-sandbox-token" # optional
2784
```
2885

29-
### Check your configuration
86+
### Verify your setup
3087

3188
```bash
3289
openapi info
3390
```
3491

3592
This shows all 5 environment variables, their status, and the scopes attached to your tokens.
3693

37-
## Sandbox Mode
94+
## Sandbox mode
3895

3996
Use the `-S` (or `--sandbox`) flag to run against sandbox environments:
4097

@@ -43,7 +100,26 @@ openapi -S sms send --to "+391234567890" --message "Test"
43100
openapi -S token list
44101
```
45102

46-
## Scope Aliases
103+
## Token management
104+
105+
```bash
106+
# List active tokens
107+
openapi token list
108+
109+
# List all available scopes
110+
openapi token scopes
111+
112+
# Create a new token
113+
openapi token create --scopes "sms"
114+
115+
# Check credit
116+
openapi token credit
117+
118+
# Revoke a token
119+
openapi token revoke --token "token-id"
120+
```
121+
122+
## Scope aliases
47123

48124
When creating tokens with `openapi token create --scopes`, you can use **scope aliases** instead of writing full scope strings.
49125

@@ -81,15 +157,11 @@ Each API service is mapped to an alias name. When you use an alias, it automatic
81157

82158
### Examples
83159

84-
Create a token with all SMS scopes:
85-
86160
```bash
161+
# All SMS scopes
87162
openapi token create --scopes "sms"
88-
```
89-
90-
Create a token with all SMS and Company scopes:
91163

92-
```bash
164+
# Multiple services
93165
openapi token create --scopes "sms,company"
94166
```
95167

@@ -112,7 +184,7 @@ Supported method prefixes: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
112184

113185
### Case insensitive
114186

115-
Aliases and method prefixes are **case insensitive**:
187+
Aliases and method prefixes are case insensitive:
116188

117189
```bash
118190
openapi token create --scopes "SMS"
@@ -127,26 +199,83 @@ All of the above are equivalent.
127199
If a term does not match any alias, it is passed through as a literal scope:
128200

129201
```bash
130-
# Mix aliases and literal scopes
131202
openapi token create --scopes "sms,GET:imprese.openapi.it/base"
132203
```
133204

134-
## Token Management
205+
## Available commands
206+
207+
| Command | Description |
208+
|---|---|
209+
| `info` | Show configuration status and readiness |
210+
| `token` | OAuth token management |
211+
| `ai` | AI language models |
212+
| `automotive` | Automotive data (vehicles, insurance) |
213+
| `cadastre` | Italian cadastral data |
214+
| `certified-email` | Italian certified email (PEC / Legalmail) |
215+
| `chamber-of-commerce` | Chamber of Commerce documents |
216+
| `company` | Company data and information |
217+
| `docuengine` | Official documents (Business Register, Revenue Agency, INPS) |
218+
| `domains` | .it domain management |
219+
| `esignature` | Electronic signature |
220+
| `exchange-rate` | Foreign currency exchange rates |
221+
| `geocoding` | Geocoding and reverse geocoding |
222+
| `invoice` | Electronic invoicing |
223+
| `massive-rem` | Massive Registered Electronic Mail |
224+
| `paying-bills` | Bills payment |
225+
| `pdf` | HTML to PDF conversion |
226+
| `postal-service` | Postal mail service |
227+
| `real-estate` | Real estate valuation data |
228+
| `risk` | Risk reports and scoring |
229+
| `sdi` | SDI electronic invoicing |
230+
| `sms` | SMS messaging (v2) |
231+
| `time-stamping` | Document time stamping |
232+
| `trust` | Trust verification services |
233+
| `visengine` | Official documents (Chamber of Commerce, INPS, Tax Agency) |
234+
| `zip-codes` | Zip codes, municipalities, provinces, regions |
235+
236+
Run `openapi --help` for the full list, or `openapi <command> --help` for subcommand details.
237+
238+
## Development
135239

136240
```bash
137-
# List active tokens
138-
openapi token list
241+
# Build
242+
make build
139243

140-
# List all available scopes
141-
openapi token scopes
142-
143-
# Check credit
144-
openapi token credit
244+
# Run tests
245+
make test-commands
145246

146-
# Revoke a token
147-
openapi token revoke --token "token-id"
247+
# Download/update OpenAPI specs
248+
make oas-download
148249
```
149250

150-
## Commands
251+
## Contributing
252+
253+
Contributions are always welcome! Whether you want to report bugs, suggest new features, improve documentation, or contribute code, your help is appreciated.
254+
255+
## Authors
256+
257+
- Francesco Bianco ([@francescobianco](https://www.github.com/francescobianco))
258+
- Openapi Team ([@openapi-it](https://github.com/openapi-it))
259+
260+
## Partners
261+
262+
Meet our partners using Openapi or contributing to this project:
263+
264+
- [Blank](https://www.blank.app/)
265+
- [Credit Safe](https://www.creditsafe.com/)
266+
- [Deliveroo](https://deliveroo.it/)
267+
- [Gruppo MOL](https://molgroupitaly.it/it/)
268+
- [Jakala](https://www.jakala.com/)
269+
- [Octotelematics](https://www.octotelematics.com/)
270+
- [OTOQI](https://otoqi.com/)
271+
- [PWC](https://www.pwc.com/)
272+
- [QOMODO S.R.L.](https://www.qomodo.me/)
273+
- [SOUNDREEF S.P.A.](https://www.soundreef.com/)
274+
275+
## License
276+
277+
This project is licensed under the [MIT License](LICENSE).
278+
279+
The MIT License is a permissive open-source license that allows you to freely use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software, provided that the original copyright notice and this permission notice are included in all copies or substantial portions of the software.
151280

152-
Run `openapi --help` to see all available commands, or `openapi <command> --help` for subcommand details.
281+
For more details, see the full license text at the [MIT License page](https://choosealicense.com/licenses/mit/).

0 commit comments

Comments
 (0)