CLI

ayinbox is the command line interface to AY Inbox. It signs in as you, holds one credential per host, and speaks only the public REST API, so it works against the hosted service and against any self-hosted instance you can reach.

ayinbox auth login
ayinbox campaign list
ayinbox inbox list --unseen
ayinbox api "/campaigns?limit=10"

Install

Pick one. All of them produce the same single binary.

macOS and Linux

curl -fsSL https://github.com/walidboulanouar/ayinbox/releases/latest/download/cli.sh | sh

Installs to ~/.local/bin, so it needs no root and no toolchain. The script verifies what it downloaded against the published checksum and installs nothing if they disagree, writes shell completions, and tells you the one line to add to your profile if that directory is not already on your PATH.

Windows

irm https://github.com/walidboulanouar/ayinbox/releases/latest/download/cli.ps1 | iex

Installs to %LOCALAPPDATA%\AyInbox\bin and adds it to your user PATH. No admin rights.

Homebrew (macOS and Linux)

brew install walidboulanouar/tap/ayinbox

Scoop (Windows)

scoop bucket add ayinbox https://github.com/walidboulanouar/homebrew-tap
scoop install ayinbox

Docker, for CI or anywhere installing a binary is more trouble than pulling one:

docker run --rm -e AYINBOX_TOKEN ghcr.io/walidboulanouar/ayinbox/cli campaign list

A container has no browser, so sign in with AYINBOX_TOKEN rather than auth login.

From source, if you have Go:

go install github.com/walidboulanouar/ayinbox/cmd/cli@latest
mv "$(go env GOPATH)/bin/cli" "$(go env GOPATH)/bin/ayinbox"

The package directory is cmd/cli, so go install names the binary cli. Rename it, or use one of the channels above.

Already have an AY Inbox instance? The binary ships inside the backend image:

docker compose -p ayinbox exec backend ayinbox --help

Keeping it current

ayinbox version
ayinbox upgrade

upgrade replaces the binary in place, verifying the download against the release checksums first. When the CLI came from Homebrew or Scoop it says which command to run instead, rather than overwriting a file a package manager owns. The CLI also checks for a new release once a day and mentions it in one line; AYINBOX_NO_UPDATE_CHECK=1 turns that off, and it never runs in CI or when output is piped.

Installer flags

The install script takes flags after --, and every one of them is also an environment variable, so the same install runs from Ansible, cloud-init or a Dockerfile:

curl -fsSL https://github.com/walidboulanouar/ayinbox/releases/latest/download/cli.sh | sh -s -- --dir /usr/local/bin
curl -fsSL https://github.com/walidboulanouar/ayinbox/releases/latest/download/cli.sh | sh -s -- --version v1.4.0
curl -fsSL https://github.com/walidboulanouar/ayinbox/releases/latest/download/cli.sh | sh -s -- --no-modify-path --no-completions
curl -fsSL https://github.com/walidboulanouar/ayinbox/releases/latest/download/cli.sh | sh -s -- --dry-run
curl -fsSL https://github.com/walidboulanouar/ayinbox/releases/latest/download/cli.sh | sh -s -- --uninstall

--help lists them in the terminal. sh -s -- --help works through the pipe.

Reading it before you run it

Piping a script into a shell is worth being careful about, which is why the checksum is published next to it:

curl -fsSLO https://github.com/walidboulanouar/ayinbox/releases/latest/download/cli.sh
curl -fsSLO https://github.com/walidboulanouar/ayinbox/releases/latest/download/cli.sh.sha256
sha256sum -c cli.sh.sha256
less cli.sh && sh cli.sh

Every release archive is covered by checksums.txt on the release, and the installer verifies the archive against it before unpacking. If the two disagree it installs nothing and says so.

Completions

The installer writes them for your shell. To do it by hand:

ayinbox completion bash > /etc/bash_completion.d/ayinbox
ayinbox completion zsh  > "${fpath[1]}/_ayinbox"
ayinbox completion fish > ~/.config/fish/completions/ayinbox.fish

Signing in

ayinbox auth login

It asks two questions: which instance (the hosted service, or a hostname of your own), and how (a browser approval, or pasting a key you already have).

The browser path shows an eight character code, opens app.ayinbox.com/cli, and waits. You approve there, choosing which workspace the CLI is signing in to. The client name and machine name on that screen are whatever the terminal reported, so check that the code matches the one your terminal printed. Because approving creates a lasting credential, the screen asks you to confirm it is you (password or second factor) if you have not done so in the last few minutes, the same as creating an API key. The approval creates one API key named for your machine (its hostname up to the first dot), which appears under Settings > API keys and is revocable there or with ayinbox auth logout. The terminal never handles your password, and the browser never handles the key.

  Your code: K4TM-9RQD
  Approve at: https://app.ayinbox.com/cli?code=K4TM-9RQD

… Waiting for approval (the code expires in 10 minutes)
✓ Signed in to ayinbox.com as [email protected]
  Workspace Acme

Non-interactive forms, for a script or an agent:

ayinbox auth login --hostname ayinbox.acme.com --web
echo "$AYINBOX_KEY" | ayinbox auth login --with-token
ayinbox auth login --scopes read-only

Scopes

The CLI asks for full access by default. The key it gets never carries more than your role in the chosen workspace allows: the approval screen lists the scopes the key will actually have for that workspace, and anything the CLI asked for beyond your role is left out. If your role allows none of them, the approval is refused with cli_auth_scopes_role. Narrow the request with --scopes:

ayinbox auth login --scopes read-only
ayinbox auth login --scopes read_campaigns,read_contacts,send_campaigns

A key's scopes are fixed once created, so widening them means a new key. ayinbox auth refresh --scopes full runs the sign-in again and revokes the key it replaces, which is why refreshing does not leave a trail of keys behind.

Scope names are the ones in the permissions reference, in either case, with full and read-only as shorthands.

Several instances

The CLI holds one credential per host. The * in auth status is the one commands use.

ayinbox auth login --hostname ayinbox.acme.com
ayinbox auth status
ayinbox auth switch ayinbox.acme.com
ayinbox campaign list --host ayinbox.com   # one command, other host

ayinbox auth status also tells you where the token came from, which is the answer nine times out of ten when a command fails unexpectedly:

* ayinbox.com
    ✓ signed in as [email protected]
    - workspace: Acme
    - scopes: all 24
    - api: https://api.ayinbox.com
    - token from: /home/jane/.config/ayinbox/hosts.yml
    - token: aybox_ab********wxyz

In CI

Set AYINBOX_TOKEN and skip the login entirely. It overrides the file and is never written to it.

env:
  AYINBOX_TOKEN: ${{ secrets.AYINBOX_TOKEN }}
  AYINBOX_HOST: ayinbox.com     # omit for the hosted service
run: ayinbox campaign list --json

ayinbox auth token prints the active token and nothing else, for handing to another tool.

Output

Commands print a table on a terminal and JSON everywhere else, so the same command is readable by a person and parseable by a pipe.

ayinbox campaign list                      # a table
ayinbox campaign list > campaigns.json     # JSON, no flag needed
ayinbox campaign list --json | jq '.data[].name'
ayinbox campaign list --fields name,status
ayinbox campaign list --template '{{range .data}}{{.name}}{{"\n"}}{{end}}'

--all walks the cursor on any list command and merges every page into one response.

Sending real mail

Anything that puts mail on the wire asks first, and refuses rather than sending when there is no terminal to ask on:

$ ayinbox campaign start 6f1c…
! `ayinbox campaign start` sends real mail. Continue? [y/N]

--yes is the only way past it, which makes it the flag to grep for in a script review. The commands that behave this way are campaign start, campaign test, placement test, placement batch-start, mailbox send, inbox reply, inbox compose and inbox approve-draft. A flagged agent draft answers draft_flagged to inbox approve-draft until you read its flags and pass --acknowledge-flags.

Commands

Run ayinbox <command> --help for the flags, and ayinbox <command> <subcommand> --help for one command's arguments.

Examples

# Create a campaign, add a step, check it, start it
ayinbox campaign create --name "Q3 outbound" --daily-limit 40
ayinbox campaign add-step CAMPAIGN_ID --subject "Quick question" --wait-after 0
ayinbox campaign preflight CAMPAIGN_ID
ayinbox campaign start CAMPAIGN_ID

# Mailbox health across the workspace
ayinbox mailbox list
ayinbox mailbox check MAILBOX_ID
ayinbox mailbox edit MAILBOX_ID --daily-limit 40

# Send as a verified Gmail alias, and take the signature from Gmail
ayinbox mailbox identity MAILBOX_ID
ayinbox mailbox refresh-identity MAILBOX_ID --signature
ayinbox mailbox edit MAILBOX_ID --send-as [email protected]

# One contact is away: hold their sequence without unsubscribing them
ayinbox campaign pause-lead CAMPAIGN_ID CONTACT_ID --until 2026-09-21T17:00:00Z --reason "On holiday"
ayinbox campaign resume-lead CAMPAIGN_ID CONTACT_ID

# Two people at one company: copy the second on the first lead's emails
ayinbox campaign lead-cc-suggestions CAMPAIGN_ID CONTACT_ID
ayinbox campaign set-lead-cc CAMPAIGN_ID CONTACT_ID --cc COLLEAGUE_ID

# The inbox
ayinbox inbox list --unseen --limit 20
ayinbox inbox thread --email-id EMAIL_ID

# Contacts in and out
ayinbox contact create --email [email protected] --first-name Jane --company Acme
ayinbox contact list --all --json > contacts.json

What needs the dashboard

Three things the CLI deliberately does not do, because the API does not let a key do them:

• Connecting a mailbox. It needs OAuth consent or a credential form in a browser. ayinbox browse mailboxes opens the right page.
• Workspace administration. Members, roles, invitations, workspace exports and the danger zone are session-only on the API: they depend on a human-bound session and refuse an API key. ayinbox browse members and ayinbox browse settings open them.
• Billing. Plans, checkout and credits are session-only for the same reason. ayinbox browse billing.

ayinbox org view still shows which workspace you are in, and ayinbox team, ayinbox settings and ayinbox audit cover the workspace surface a key can reach.

Watching events

ayinbox events tail streams the developer WebSocket into your terminal: the same events the dashboard runs on, printed as they happen. It is the fastest way to see whether an integration is receiving what you think it is, without standing up a public endpoint first.

ayinbox events tail
ayinbox events tail --intent EMAIL --intent CAMPAIGN
ayinbox events tail --json | jq 'select(.event_type == "EMAIL_REPLIED")'

It needs a key with REALTIME_SUBSCRIBE; ayinbox auth refresh --scopes full gets one. The stream, its intents and its event types are documented under Realtime.

Calling the API directly

ayinbox api reaches every endpoint, including the ones with no command of their own. Paths are relative to /v1.

ayinbox api /me
ayinbox api "/campaigns?limit=10" --paginate
ayinbox api /contacts -f [email protected] -f first_name=Jane
ayinbox api /campaigns/CAMPAIGN_ID -X PATCH -F daily_limit=40
ayinbox api /contacts/search -X POST --input filter.json
ayinbox api /webhooks/WEBHOOK_ID -X DELETE

-f keeps a value a string. -F guesses the type, so true, false, null and numbers arrive as themselves, @file reads a value from a file, key[sub]=v nests and repeated key[]=v builds an array. --paginate follows the cursor, -i includes the status and headers, --idempotency-key rides the documented header.

Configuration

Two files under ~/.config/ayinbox (or XDG_CONFIG_HOME, or AYINBOX_CONFIG_DIR):

• hosts.yml, one credential per host, written 0600
• config.yml, preferences and aliases

Signing in records the instance's own API and dashboard URLs alongside the credential, taken from what the instance reports, so browse and events tail work on a self-hosted layout without anyone configuring a second address.

ayinbox config list
ayinbox config set output json      # default to JSON even on a terminal
ayinbox config set confirm always   # confirm every write, not only sends
ayinbox config set browser firefox

Aliases

ayinbox alias set hot "campaign list --status active"
ayinbox hot --json

Anything you type after the alias is appended, so an alias is a starting point rather than a fixed command.

Environment

Exit codes

Every API failure prints the response's machine-readable code and request_id to stderr, so a script can branch without reading prose.

See also

• Authentication for how the device flow mints a key
• Permissions for what each scope allows
• Endpoint scope map for what ayinbox api can reach
• Realtime for the stream behind ayinbox events tail
• ayinboxctl for the operator's CLI