📭 frontcli — Front in your terminal

Agent Skill

This CLI is available as an open agent skill for AI assistants including Claude Code, OpenClaw, Codex, Cursor, GitHub Copilot, and 35+ agents.

npx skills add dedene/frontapp-cli

Fast, script-friendly CLI for Front. Manage conversations, messages, contacts, tags, and more from the command line. JSON output, multiple accounts, and secure credential storage built in.

Features

Conversations - list/search/get, messages/comments, archive/open/trash, assign/unassign, snooze, follow, custom fields
Messages - get, send, reply, attachments + download
Drafts - create, list, get, update, delete
Signatures - list teammate signatures, get a signature
Tags - list/tree, get, create, update, delete, children, convos
Contacts - list/search/get, handles, notes, convos, create/update/delete/merge
Inboxes - list/get, convos, channels
Teammates - list/get, convos
Channels - list, get
Comments - list/get/create (internal discussions)
Templates - list/get/use (canned responses)
Whoami - show authenticated user
Multiple accounts - manage multiple Front accounts with aliases
Secure credential storage using OS keyring (macOS Keychain, Linux Secret Service)
Auto-refreshing tokens - authenticate once, use indefinitely
Parseable output - JSON or TSV (--plain) mode for scripting and automation

Installation

Homebrew

brew install dedene/tap/frontcli

Go Install

go install github.com/dedene/frontapp-cli/cmd/frontcli@latest

Build from Source

git clone https://github.com/dedene/frontapp-cli.git
cd frontapp-cli
make build
./bin/frontcli --help

Quick Start

1. Create a Front OAuth App

Before using frontcli, create an OAuth app in Front:

Go to Settings → Developers in Front: https://app.frontapp.com/settings/developers
Click "New app"
Configure the OAuth settings (see detailed guide below)
Save to generate your Client ID and Client Secret

2. Store OAuth Credentials

frontcli auth setup <client_id>

The client secret will be prompted securely (hidden input).

3. Authenticate

frontcli auth login

This opens a browser for OAuth authorization. On first use, you'll see a browser security warning because frontcli uses a self-signed certificate for localhost. Click "Advanced" → "Proceed to localhost" (Chrome) or similar in other browsers. This is a one-time step.

The refresh token is stored securely in your system keychain.

4. Test

frontcli conv list --limit 5
frontcli inboxes list
frontcli teammates list

Setting Up Your Front OAuth App

When creating a new app in Front's developer settings, configure these options:

1. Enable OAuth

Navigate to the Features tab, click Add Feature, and select OAuth to enable it.

2. Redirect URLs

Click "Add Redirect URL" and add:

https://localhost:8484/callback

This is the callback URL that frontcli uses during the OAuth flow. frontcli runs a local HTTPS server with a self-signed certificate to receive the OAuth callback.

3. Namespace Access

Select which namespaces your app can access:

Option	Description
Global resources	Company-wide resources (recommended)
Shared resources	Shared inboxes and conversations
Private resources	Private inboxes (if needed)

For full access, check all three boxes.

4. Resource Permissions

Select permissions for each resource type. Here are the recommended permissions for full CLI functionality:

Resource	Read	Write	Delete
Accounts	✓
Attachments	✓
Channels	✓
Comments	✓	✓
Contacts	✓	✓	✓
Conversations	✓	✓
Signatures	✓
Drafts	✓	✓	✓
Inboxes	✓
Message templates	✓
Messages	✓	✓	✓
Tags	✓	✓	✓
Teammates	✓

Tip: Start with Read permissions only if you just want to query data. Add Write/Delete/Send as needed.

5. Save and Get Credentials

Click Save at the bottom
Your Client ID and Client Secret will be generated
Copy these values for the frontcli auth setup command

Authentication

Storing Credentials

# Store OAuth credentials (prompted securely for secret)
frontcli auth setup <client_id>
# Or for CI/scripts, use the flag:
# frontcli auth setup <client_id> --client-secret="$FRONT_CLIENT_SECRET"
# Authenticate with Front
frontcli auth login
# Check authentication status
frontcli auth status
# List authenticated accounts
frontcli auth list
# Log out
frontcli auth logout

Multiple Accounts

Use the --account flag or FRONT_ACCOUNT environment variable:

# Via flag
frontcli conv list --account work@company.com
# Via environment
export FRONT_ACCOUNT=work@company.com
frontcli conv list

Override OAuth client selection with --client:

frontcli --client work-client conv list

Keyring Backend

Tokens are stored securely using your system's keyring:

macOS: Keychain Access
Linux: Secret Service (GNOME Keyring, KWallet)

For environments without a keyring (CI, containers), use the file backend:

export FRONT_KEYRING_BACKEND=file
export FRONT_KEYRING_PASSWORD='your-password'
frontcli auth login

Commands

Conversations

# List conversations
frontcli conv list
frontcli conv list --inbox inb_xxx --limit 10
frontcli conv list --status open
frontcli conv list --tag tag_xxx
# Get conversation details
frontcli conv get cnv_xxx
frontcli conv get cnv_xxx -m # Include message summaries
frontcli conv get cnv_xxx -c # Include comment summaries
frontcli conv get cnv_xxx -m -c # Both messages and comments
frontcli conv get cnv_xxx --full # Full content with comments inline (timeline)
frontcli conv get cnv_xxx --full --html # Show HTML body
frontcli conv get cnv_xxx --full --text # Show plain text body
frontcli conv messages cnv_xxx
frontcli conv comments cnv_xxx
# Search conversations
frontcli conv search "customer issue"
frontcli conv search --from client@co.com --tag tag_xxx --status open
# Manage conversation status
frontcli conv archive cnv_xxx cnv_yyy # Archive multiple
frontcli conv archive --ids-from - # Read IDs from stdin
frontcli conv open cnv_xxx # Unarchive
frontcli conv trash cnv_xxx # Move to trash
# Assign conversation
frontcli conv assign cnv_xxx --to tea_xxx
frontcli conv unassign cnv_xxx
# Snooze
frontcli conv snooze cnv_xxx --until "2024年01月15日T09:00:00Z"
frontcli conv unsnooze cnv_xxx
# Followers
frontcli conv followers cnv_xxx
frontcli conv follow cnv_xxx
frontcli conv unfollow cnv_xxx
# Custom fields
frontcli conv update cnv_xxx --field "Priority=High" --field "Category=Support"
# Manage tags
frontcli conv tag cnv_xxx tag_xxx # Add tag
frontcli conv untag cnv_xxx tag_xxx # Remove tag

Messages

# Get message
frontcli msg get msg_xxx
frontcli msg get msg_xxx --raw # Show raw HTML body
# Send new message
frontcli msg send --channel cha_xxx --to user@example.com --subject "Hello" --body "Message body"
frontcli msg send --channel cha_xxx --to user@example.com --body-file ./message.txt
# Reply to conversation
frontcli msg reply cnv_xxx --body "Thanks for reaching out"
frontcli msg reply cnv_xxx --body-file ./reply.txt
# List attachments
frontcli msg attachments msg_xxx
# Download attachment
frontcli msg attachment download att_xxx -o ./file.pdf

Drafts

# Create draft (reply to conversation)
frontcli drafts create cnv_xxx --channel cha_xxx --author tea_xxx --inbox inb_xxx --body "Draft reply"
# Create draft without adding the default signature
frontcli drafts create cnv_xxx --channel cha_xxx --author tea_xxx --inbox inb_xxx --no-default-signature --body "Draft reply"
# Create draft with an explicit signature
frontcli drafts create cnv_xxx --channel cha_xxx --author tea_xxx --inbox inb_xxx --signature sig_xxx --body "Draft reply"
# Create draft (new message via channel)
frontcli drafts create --channel cha_xxx --to user@example.com --author tea_xxx --inbox inb_xxx --body "Draft message"
# Create shared draft and assign to a different teammate
frontcli drafts create --channel cha_xxx --to user@example.com --author tea_xxx --inbox inb_xxx --assignee tea_yyy --mode shared --body "Shared draft"
# List drafts in conversation
frontcli drafts list cnv_xxx
# Get draft
frontcli drafts get dra_xxx
# Update draft (optimistic locking with version)
frontcli drafts update dra_xxx --body "Updated draft" --draft-version draft-ver-123
frontcli drafts update dra_xxx --channel cha_xxx --body-file ./reply.html --draft-version draft-ver-123
# Delete draft
frontcli drafts delete dra_xxx --draft-version draft-ver-123

Signatures

# List signatures for a teammate
frontcli signatures list --teammate tea_xxx
# Get one signature
frontcli signatures get sig_xxx

Contacts

# List contacts
frontcli contacts list
frontcli contacts list --limit 50
frontcli contacts search "john"
# Get contact
frontcli contacts get ctc_xxx
frontcli contacts handles ctc_xxx
# Manage handles
frontcli contacts handle add ctc_xxx --type email --value new@example.com
frontcli contacts handle delete hdl_xxx
# Notes
frontcli contacts notes ctc_xxx
frontcli contacts note add ctc_xxx --body "Important customer"
# Conversations for contact
frontcli contacts convos ctc_xxx
# Create contact
frontcli contacts create --handle email:user@example.com --name "John Doe"
frontcli contacts create --handle phone:+1234567890 --name "Jane Doe"
# Update contact
frontcli contacts update ctc_xxx --name "John Smith"
# Delete contact
frontcli contacts delete ctc_xxx
# Merge contacts
frontcli contacts merge ctc_source ctc_target

Other Resources

# Inboxes
frontcli inboxes list
frontcli inboxes get inb_xxx
frontcli inboxes convos inb_xxx
frontcli inboxes channels inb_xxx
# Teammates
frontcli teammates list
frontcli teammates get tea_xxx
frontcli teammates convos tea_xxx
# Channels
frontcli channels list
frontcli channels get cha_xxx
# Comments (internal discussions)
frontcli comments list cnv_xxx
frontcli comments get cmt_xxx
frontcli comments create cnv_xxx --body "Internal note"
# Templates
frontcli templates list
frontcli templates get rsp_xxx
frontcli templates use rsp_xxx
# Whoami
frontcli whoami

Output Formats

Human-Readable (Default)

$ frontcli conv list --limit 3
ID STATUS ASSIGNEE SUBJECT CREATED
cnv_abc123 open alice@company.com Re: Order question 2025年01月15日 10:30
cnv_def456 archived bob@company.com Invoice inquiry 2025年01月14日 15:45
cnv_ghi789 open - New customer request 2025年01月14日 09:20

JSON (for scripting)

$ frontcli conv list --limit 1 --json
{
 "_results": [
 {
 "id": "cnv_abc123",
 "subject": "Re: Order question",
 "status": "open",
 ...
 }
 ]
}

Use JSON output with jq for powerful scripting:

# Get IDs of all open conversations
frontcli conv list --status open --json | jq -r '._results[].id'
# Archive all conversations with a specific tag
frontcli conv list --tag tag_xxx --json | jq -r '._results[].id' | xargs frontcli conv archive

Plain (TSV)

$ frontcli conv list --limit 1 --plain
cnv_abc123	open	alice@company.com	Re: Order question	2025年01月15日 10:30

Configuration

Environment Variables

Variable	Description
`FRONT_ACCOUNT`	Default account email (avoids `--account` flag)
`FRONT_JSON`	Set to `1` for JSON output by default
`FRONT_PLAIN`	Set to `1` for TSV output by default
`FRONT_KEYRING_BACKEND`	Keyring backend: `auto`, `keychain`, `file`
`FRONT_KEYRING_PASSWORD`	Password for file-based keyring

Config File

Config is stored at:

macOS: ~/Library/Application Support/frontcli/config.yaml
Linux: ~/.config/frontcli/config.yaml

default_account: work@company.com
account_aliases:
 work: work@company.com
 personal: me@gmail.com
default_output: text # text | json | plain
timezone: UTC

Config Commands

# Show config paths
frontcli config path

Shell Completions

Generate completions for your shell:

# Bash
frontcli completion bash > /etc/bash_completion.d/frontcli
# Or: eval "$(frontcli completion bash)"
# Zsh
frontcli completion zsh > "${fpath[1]}/_frontcli"
# Or: eval "$(frontcli completion zsh)"
# Fish
frontcli completion fish > ~/.config/fish/completions/frontcli.fish

Development

# Install tools
make tools
# Format code
make fmt
# Lint
make lint
# Test
make test
# Build
make build

Security

OAuth credentials are stored in ~/.config/frontcli/clients/ with 0600 permissions
Refresh tokens are stored in your system's secure keyring
Access tokens are kept in memory only and refreshed automatically
Never commit credentials to version control

License

MIT

Name		Name	Last commit message	Last commit date
.claude/skills/frontcli		.claude/skills/frontcli
.github/workflows		.github/workflows
cmd/frontcli		cmd/frontcli
internal		internal
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Latest commit

History

Folders and files

Repository files navigation