CLI Overview

Complete guide to the Vestauth command-line interface

Introduction

The Vestauth CLI provides tools to create agent identities, sign HTTP requests, verify signatures, and run your own Vestauth infrastructure.

Installation

npm

npm i -g vestauth

curl

curl -sfS https://vestauth.sh | sh

GitHub Releases

curl -L -o vestauth.tar.gz "https://github.com/vestauth/vestauth/releases/latest/download/vestauth-$(uname -s)-$(uname -m).tar.gz"
tar -xzf vestauth.tar.gz
./vestauth agent init

Command Groups

Vestauth organizes commands into logical groups:

Command Group	Description	Icon
agent	Create and manage agent identities	▶️
tool	Verify agent requests in your tools	🔨
server	Run your own Vestauth server	🖥️
primitives	Low-level cryptographic operations	🔩

Global Options

These options work with all commands:

--log-level · string · default: "info"

Set log level: error, warn, info, verbose, debug

--quiet · boolean

Set log level to error (shorthand)

--verbose · boolean

Set log level to verbose (shorthand)

--debug · boolean

Set log level to debug for troubleshooting

Quick Examples

Create an Agent

vestauth agent init

✔ agent created (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)

Call a Tool

vestauth agent curl https://api.vestauth.com/whoami --pp

{
  "uid": "agent-609a4fd2ebf4e6347108c517",
  "kid": "FGzgs758DBGnI1S0BejChDsK0IKZm3qPpOOXdRnnBkM",
  "public_jwk": {
    ...
  },
  "well_known_url": "https://agent-609a4fd2ebf4e6347108c517.api.vestauth.com/.well-known/http-message-signatures-directory"
}

Verify a Request

vestauth tool verify GET https://api.vestauth.com/whoami \
  --signature "sig1=:H1kxwSRWFbIzKbHaUy4hQFp/JrmVTX//72JPHcW4W7cPt9q6LytRJgx5pUgWrrr7DCcMWgx/jpTPc8Ht8SZ3CQ==:" \
  --signature-input "sig1=(\"@authority\");created=1770396709;keyid=\"FGzgs758DBGnI1S0BejChDsK0IKZm3qPpOOXdRnnBkM\";alg=\"ed25519\";expires=1770397009;nonce=\"BZSDVktdkjO6XH5jafAdPDttsB6eytXO7u8KXJN1tMtd5bprE3rp08HiaTRo7H6gZGtYb4_qtL7RiGi8P2Gq7w\";tag=\"web-bot-auth\"" \
  --signature-agent "sig1=agent-609a4fd2ebf4e6347108c517.api.vestauth.com"

Getting Help

Display help for any command:

vestauth help
vestauth help agent
vestauth agent init --help

Next Steps

Agent Commands

Create identities and call tools

Tool Commands

Verify agent requests

Server Commands

Self-host Vestauth

Primitives

Low-level cryptographic operations