frontapp-cli

📮 Front CLI

Agent-first CLI for the Front API. Every command returns structured HATEOAS JSON that tells the agent what to do next.

Install

go install github.com/joshuap/frontapp-cli/cmd/front@latest

Or build from source:

git clone https://github.com/joshuap/frontapp-cli.git
cd frontapp-cli
go build -o front ./cmd/front
cp front ~/.local/bin

Configure

export FRONT_API_TOKEN="your-api-token"
export FRONT_USER="user@example.com"

Or use a config file:

# macOS: ~/Library/Application Support/front/config.yaml
# Linux: ~/.config/front/config.yaml
user: user@example.com

Environment variables take precedence over config. Run front config to verify.

Token Command

Instead of setting FRONT_API_TOKEN directly, you can configure a token_command to resolve the token dynamically from a secret manager:

token_command:
  - op
  - read
  - op://Vault/front_api_token/password

Each list element is a separate argument. The command is executed directly and its stdout is used as the token.

Usage

front                                    # list available commands
front config                             # show current configuration
front inboxes                            # list inboxes
front inbox                              # search conversations (default: is:open is:unassigned)
front inbox --assignee user@example.com  # filter by assignee
front read <conversation-id>             # read a conversation thread

Output Format

Every command returns a JSON envelope:

{
  "ok": true,
  "command": "front inboxes",
  "result": {
    "count": 2,
    "inboxes": [
      { "id": "inb_123", "name": "Support" },
      { "id": "inb_456", "name": "Sales" }
    ]
  },
  "next_actions": [
    {
      "command": "front inbox <inbox-id>",
      "description": "Search conversations in this inbox"
    }
  ]
}

Errors include a fix field:

{
  "ok": false,
  "command": "front inboxes",
  "error": { "message": "no API token provided", "code": "UNAUTHORIZED" },
  "fix": "Set FRONT_API_TOKEN or configure token_command in ~/.config/front/config.yaml"
}

Agent Skill

Install the skill so agents can use the CLI automatically:

npx skills add joshuap/frontapp-cli

Or manually:

ln -s /path/to/frontapp-cli/skills/front ~/.claude/skills/front

Inspiration

The agent-first HATEOAS design is inspired by Joel Hooks' work on joelclaw — particularly Joel's email CLI and cli-design skill.

License

MIT