🔑 Ortie

CLI to manage OAuth tokens

Table of contents

• Features
• Installation
• Configuration
  • Google
  • Microsoft
• Usage
  • Request new access token
  • Refresh access token
  • Show access token
• Alternatives
• FAQ
• Social
• Sponsoring

Features

• OAuth 2.0 support:
  • Authorization Code Grant rfc6749 #4.1
  • Refreshing an access token rfc6749 #6
• PKCE support rfc7636
• Native TLS support via native-tls crate (requires native-tls feature)
• Rust TLS support via rustls crate with:
  • AWS crypto support (requires rustls-aws feature)
  • Ring crypto support (requires rustls-ring feature)
• Fake HTTP redirection server
• Shell command and keyring storages (requires command and keyring features)
• Shell command and system notification hooks (requires command and notify features)
• JSON support with --json

Ortie CLI is written in Rust, and relies on cargo features to enable or disable functionalities. Default features can be found in the features section of the Cargo.toml, or on docs.rs.

Installation

Pre-built binary

Ortie CLI can be installed with the installer:

As root:

curl -sSL https://raw.githubusercontent.com/pimalaya/ortie/master/install.sh | sudo sh

As a regular user:

curl -sSL https://raw.githubusercontent.com/pimalaya/ortie/master/install.sh | PREFIX=~/.local sh

These commands install the latest binary from the GitHub releases section.

If you want a more up-to-date version than the latest release, check out the releases GitHub workflow and look for the Artifacts section. You should find a pre-built binary matching your OS. These pre-built binaries are built from the master branch, using default features.

Cargo

Ortie CLI can be installed with cargo:

cargo install ortie

You can also use the git repository for a more up-to-date (but less stable) version:

cargo install --locked --git https://github.com/pimalaya/ortie.git

Nix

Ortie CLI can be installed with Nix:

nix-env -i ortie

You can also use the git repository for a more up-to-date (but less stable) version:

nix-env -if https://github.com/pimalaya/ortie/archive/master.tar.gz

Or, from within the source tree checkout:

nix-env -if .

If you have the Flakes feature enabled:

nix profile install ortie

Or, from within the source tree checkout:

nix profile install

You can also run Ortie directly without installing it:

nix run ortie

Configuration

The wizard is not yet available (it should come soon), meanwhile you can manually edit your own configuration from scratch:

• Copy the content of the documented ./config.sample.toml
• Paste it into a new file ~/.config/ortie/config.toml
• Edit, then comment or uncomment the options you want

You will also need a registered application. This depends on your OAuth 2.0 provider. You can either use an existing application (public registration like Thunderbird) or register your own application. The first option is definitely simpler.

See public Thunderbird application credentials for various providers at github.com/mozilla.

Google

endpoints.authorization = "https://accounts.google.com/o/oauth2/auth?access_type=offline"
endpoints.token = "https://www.googleapis.com/oauth2/v3/token"
scopes = ["https://www.googleapis.com/auth/carddav", "https://mail.google.com"] # choose the right scope for your usage

Using public Thunderbird application:

client-id = "406964657835-aq8lmia8j95dhl1a2bvharmfk3t1hgqj.apps.googleusercontent.com"
client-secret.raw = "kSmqreRr0qwBWJgbf5Y-PjSU"
enpoints.redirection = "http://localhost"

Using your own application:

client-id = "<your-client-id>"
client-secret = "<your-client-secret>"

Microsoft

endpoints.authorization = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"
endpoints.token = "https://login.microsoftonline.com/common/oauth2/v2.0/token"

Using public Thunderbird application:

client-id = "9e5f94bc-e8a4-4e73-b8be-63364c29d753"
endpoints.redirection = "https://localhost"

Using your own application:

client-id = "<your-client-id>"
client-secret = "<your-client-secret>"

Usage

Request new access token

$ ortie auth get

Created authorization request with:
 - state: RWdzST0ybUIzT1wtMSF9OCMmJHJUVmJrUmhhU0haLz4
 - pkce: oJ-rEXNu9YzqpCWVIPOwD5KvMhLAT73dstk0jye8nZ6

Sending authorization request to your browser…
Spawning fake HTTP redirection server…
Waiting for redirection…

Go to your browser, follow the instructions, then you should see:

Authorization succeeded!

Go back to your terminal, you should see:

Continue authorization process…
Access token successfully issued (expires in 1h)

In case the redirections fails, for example:

$ ortie auth get

Created authorization request with:
 - state: RWdzST0ybUIzT1wtMSF9OCMmJHJUVmJrUmhhU0haLz4
 - pkce: oJ-rEXNu9YzqpCWVIPOwD5KvMhLAT73dstk0jye8nZ6

Sending authorization request to your browser…
Spawn fake HTTP redirection server…
Error: Permission denied (os error 13)

Go to your browser, follow the instructions, then copy the URL you are redirected to (it should fail since the fake HTTP redirection server did not start).

Go back to your terminal, and complete the authorization flow:

ortie auth resume \
  --state RWdzST0ybUIzT1wtMSF9OCMmJHJUVmJrUmhhU0haLz4 \
  --pkce oJ-rEXNu9YzqpCWVIPOwD5KvMhLAT73dstk0jye8nZ6 \
  https://localhost/?code=M.C521_BAY.2.U&state=RWdzST0ybUIzT1wtMSF9OCMmJHJUVmJrUmhhU0haLz4

Refresh access token

$ ortie token refresh

Access token successfully refreshed (expires in 1h)

Show access token

$ ortie token show

EwA4BOl3BAAUcDnR9grBJokeAHaUV8R3+rVHX+IAAQfw9oZLztQS8bo8NvyWmbs…

The --auto-refresh argument (as well as the config option auto-refresh = true) automatically refreshes expired tokens.

You can also inspect token metadata:

$ ortie token inspect

Token type: bearer
Issued: 22h 51m 1s ago
Expires in: 52m 38s
With refresh token: true
With scope: https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/SMTP.Send

Alternatives

• pizauth: daemon-oriented alternative
• oama: haskell alternative
• mutt_oauth2.py: python script alternative

FAQ

How to debug Ortie CLI?

The simplest way is to use --debug and/or --trace arguments.

The advanced way is based on environment variables:

• RUST_LOG=<level>: determines the log level filter, can be one of off, error, warn, info, debug and trace.
• RUST_BACKTRACE=1: enables the full error backtrace, which include source lines where the error originated from.

Logs are written to the stderr, which means that you can redirect them easily to a file:

ortie token show --debug 2>/tmp/ortie.log

Social

• Chat on Matrix
• News on Mastodon or RSS
• Mail at pimalaya.org@posteo.net

Sponsoring

Special thanks to the NLnet foundation and the European Commission that have been financially supporting the project for years:

• 2022: NGI Assure
• 2023: NGI Zero Entrust
• 2024: NGI Zero Core (still ongoing in 2026)

If you appreciate the project, feel free to donate using one of the following providers: