htrust

Open Source Trust for Humans.

htrust is a Rust CLI for Linux sysadmins, shell scripts, and agentic tooling that need to check whether real-world information can be trusted before acting on it.

The interface is intentionally flat: one command per claim type, one positional value to check, a short status on stdout and a meaningful exit code.

Installation

Build from source

You need a working Rust toolchain (edition 2021 or newer) and cargo.

git clone https://github.com/openapi/htrust.git
cd htrust
cargo build --release

The binary is produced at:

target/release/htrust

Local install with Make

make install

This builds the release binary and copies it to ~/.local/bin/htrust. Make sure ~/.local/bin is in your PATH.

To install to a custom prefix:

make install PREFIX=/usr/local

The binary will be copied to $PREFIX/bin/htrust.

Configuration

htrust reads API tokens from the environment.

Variable	Required by	Description
`OPENAPI_TOKEN`	production commands	Production token for `trust.openapi.com`
`OPENAPI_SANDBOX_TOKEN`	`--sandbox` commands	Sandbox token for `test.trust.openapi.com`

Set them in your shell or in a .env file:

export OPENAPI_TOKEN=your-production-token
export OPENAPI_SANDBOX_TOKEN=your-sandbox-token

A ready-to-edit example is provided in .env.example.

Static validation first

htrust never calls the remote trust API unless the input passes a local stack of static validators. Every command runs format, checksum and sanity checks before any network request is made.

Why? Because trust decisions should be cheap, fast and privacy-friendly. If an email is syntactically broken, a phone number is not E.164, an IP is not parseable or a URL has no valid scheme, the tool rejects it immediately without leaking the value to a third party and without consuming API quota.

htrust email not-an-email
# error: invalid email format: not-an-email

Local validators currently cover:

Kind	Static checks
`mobile`	E.164 format (`+` followed by 2-15 digits)
`email`	Basic RFC-like structure (`local@domain.tld`)
`ip`	Valid IPv4 or IPv6 address
`url`	Valid URL with `http` or `https` scheme

This "validate before you trust" principle is a core design goal of htrust.

Commands

`htrust info`

Prints runtime configuration: sandbox mode, token status, and CLI version.

htrust info

Example output:

htrust runtime
sandbox: false
token env: OPENAPI_TOKEN (set)

info does not perform any API call.

`htrust mobile`

Verifies a mobile phone number.

# basic check — prints a short status and sets the exit code
htrust mobile +393331234567
# advanced / detailed endpoint
htrust mobile +393331234567 --detail
# full JSON response
htrust mobile +393331234567 --json
htrust mobile +393331234567 --full

Argument	Description
`VALUE`	Phone number with international prefix (e.g. `+393331234567`)

--detail selects the richer endpoint when the API exposes both a base and an advanced check. --json / --full print the full API response instead of the short status.

`htrust email`

Verifies an email address.

htrust email info@example.com
htrust email info@example.com --detail
htrust email info@example.com --json

Argument	Description
`VALUE`	Email address to verify

`htrust ip`

Verifies an IP address.

htrust ip 8.8.8.8
htrust ip 8.8.8.8 --json

Argument	Description
`VALUE`	IPv4 or IPv6 address

--detail is accepted for interface consistency but the underlying endpoint is always the advanced one.

`htrust url`

Verifies a URL.

htrust url https://example.com
htrust url https://example.com --json

Argument	Description
`VALUE`	Absolute URL to verify

Like ip, --detail is accepted but maps to the advanced endpoint.

Global flags

Flag	Description
`--sandbox`	Use the sandbox environment (`test.trust.openapi.com`) and `OPENAPI_SANDBOX_TOKEN`
`--detail` / `--details`	Use the richer endpoint where available (synonyms)
`--json`, `--full`	Print the full API response as JSON
`-h`, `--help`	Print help
`-V`, `--version`	Print version

Examples:

htrust --sandbox info
htrust --sandbox mobile +393331234567 --detail
htrust email info@example.com --json

Endpoint mapping

Command	Default endpoint	`--detail` endpoint
`mobile`	`mobile-start`	`mobile-advanced`
`email`	`email-start`	`email-advanced`
`ip`	`ip-advanced`	`ip-advanced`
`url`	`url-advanced`	`url-advanced`

Base URL:

production: https://trust.openapi.com
sandbox: https://test.trust.openapi.com

The final URL is built as:

{base_url}/{endpoint}/{value}

For example:

https://trust.openapi.com/mobile-start/+393331234567

Exit codes

Code	Meaning
`0`	Trusted result (`valid` / `verified`) or neutral/no-op
`1`	Distrusted result (`risky` / `invalid`), API error, or CLI usage error
`2`	Missing required environment variable or empty token

This makes htrust composable in shell scripts:

if htrust email info@example.com >/dev/null;thenecho"Email looks trustworthy"elseecho"Email is risky or invalid"fi

Output format

By default trust commands print a short status string to stdout:

$ htrust email info@example.com
valid

The status mirrors the API's own assessment (e.g. valid, risky, invalid). Use --json or --full to see the complete API response:

$ htrust email info@example.com --json
{
"data": { ... },
"error": null,
"message": "",
"success": true
}

Errors are printed to stderr.

Development

Build the debug binary:

cargo build

Run the CLI from the build directory:

./target/debug/htrust info

Run clippy and formatting checks:

cargo clippy --all-targets
cargo fmt --check

Testing

Rust unit tests

Unit tests live inside the source files under src/ in #[cfg(test)] modules.

cargo test

Bash smoke tests (`tests/`)

The tests/ directory contains simple, practical smoke tests. Each command has its own file that shows the real command being executed:

tests/
├── run.sh # runs all smoke tests
├── test_info.sh # htrust info in action
├── test_mobile.sh # htrust mobile in action
├── test_email.sh # htrust email in action
├── test_ip.sh # htrust ip in action
└── test_url.sh # htrust url in action

Run smoke tests:

make test-smoke

or directly:

./tests/run.sh
./tests/test_mobile.sh

Negative / side-case asserts (`tests/asserts/`)

The tests/asserts/ directory contains more formal assertions for error handling and edge cases:

tests/asserts/
├── run.sh # runs all assert tests
├── lib.sh # tiny assert helpers
├── test_info_asserts.sh # info edge cases
├── test_mobile_asserts.sh # mobile error cases
├── test_email_asserts.sh # email error cases
├── test_ip_asserts.sh # ip error cases
└── test_url_asserts.sh # url error cases

Run assert tests:

make test-asserts

or directly:

./tests/asserts/run.sh
./tests/asserts/test_mobile_asserts.sh

Run everything

make test

This runs cargo test, the smoke suite and the assert suite.

To run live tests against the sandbox:

export OPENAPI_SANDBOX_TOKEN=your-sandbox-token
make test

Makefile targets

Target	Description
`make` or `make build`	Build the release binary
`make install`	Build and install to `~/.local/bin` (or `$PREFIX/bin`)
`make test`	Run Rust unit tests, smoke tests and assert tests
`make test-smoke`	Run only the practical smoke tests
`make test-asserts`	Run only the negative/side-case assert tests
`make clean`	Remove build artifacts

Project layout

.
├── Cargo.toml
├── Makefile
├── README.md
├── .env.example
├── src/
│ ├── main.rs # CLI entrypoint
│ ├── cli.rs # clap argument definitions
│ ├── client.rs # HTTP client and auth
│ ├── config.rs # Token loading
│ └── commands/
│ ├── info.rs # htrust info
│ ├── mod.rs # command module exports
│ └── trust.rs # mobile/email/ip/url implementation
└── tests/
├── run.sh # smoke-test runner
├── test_info.sh # info command smoke test
├── test_mobile.sh # mobile command smoke test
├── test_email.sh # email command smoke test
├── test_ip.sh # ip command smoke test
├── test_url.sh # url command smoke test
└── asserts/
├── run.sh # assert-test runner
├── lib.sh # tiny assert helpers
├── test_info_asserts.sh
├── test_mobile_asserts.sh
├── test_email_asserts.sh
├── test_ip_asserts.sh
└── test_url_asserts.sh

Scope

This first cut wraps the current trust.openapi.com subset:

mobile-start
mobile-advanced
email-start
email-advanced
ip-advanced
url-advanced

The long-term shape can expand to commands like htrust iban ... or htrust vat ..., but those endpoints are not wired in this first baseline yet.

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
IDEA.md		IDEA.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md

Navigation Menu

Uh oh!

Repository files navigation

htrust

Table of contents

Installation

Build from source

Local install with Make

Configuration

Static validation first

Commands

`htrust info`

`htrust mobile`

`htrust email`

`htrust ip`

`htrust url`

Global flags

Endpoint mapping

Exit codes

Output format

Development

Testing

Rust unit tests

Bash smoke tests (`tests/`)

Negative / side-case asserts (`tests/asserts/`)

Run everything

Makefile targets

Project layout

Scope

About

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

htrust

Table of contents

Installation

Build from source

Local install with Make

Configuration

Static validation first

Commands

htrust info

htrust mobile

htrust email

htrust ip

htrust url

Global flags

Endpoint mapping

Exit codes

Output format

Development

Testing

Rust unit tests

Bash smoke tests (tests/)

Negative / side-case asserts (tests/asserts/)

Run everything

Makefile targets

Project layout

Scope

About

Topics

Resources

Stars

Watchers

Forks

Contributors

Languages

`htrust info`

`htrust mobile`

`htrust email`

`htrust ip`

`htrust url`

Bash smoke tests (`tests/`)

Negative / side-case asserts (`tests/asserts/`)