Documentation

CLI & Local Push

Push data into TailStats from your terminal, scripts, or local files.

CLI Tool

Push data to TailStats cards from the command line, scripts, or automation.

Installation

curl -fsSL https://tailstats.com/install | sh

This installs the tailstats command to /usr/local/bin.

Push Command

Send data to a TailStats card:

tailstats push <card-id> [options]

Value Options

Option Description
--value "42" Simple value (string or number)
--json '{...}' JSON object with full card data
--file ~/data.json Read JSON from file

Display Options

Option Description
--title "CPU Usage" Set item title
--type number Value type: number, string, progress, status, array
--format percent Format: percent, currency:USD, number:compact
--icon "cpu" SF Symbol name
--emoji "📊" Emoji icon
--color red Value color (name or #hex)
--columns 2 Grid columns (1-4)
--sparkline "10,20,30" Comma-separated numbers for sparkline chart
--sparkline-color green Sparkline color
--sparkline-height 50 Sparkline height (0-100)
--diff "+10,-5" Git diff stats (additions,deletions)

Menu Bar Options

Option Description
--menubar Show value in menu bar
--menubarBackground "#FF0000" Menu bar badge background color

Examples

tailstats push abc123 --value "42" --title "Active Users"
tailstats push abc123 --value "0.85" --type progress --title "CPU" --menubar
tailstats push abc123 --json '{"items":[{"title":"Revenue","type":"number","value":1234,"format":"currency:USD"}]}'
tailstats push cpu 75 --sparkline "60,65,70,72,75"
tailstats push commit "Feature X" --diff "+150,-23"

Notify Command

Send macOS notifications:

tailstats notify --message "Hello" [options]
Option Description
--title "Title" Notification title
--subtitle "Info" Subtitle text
--sound default Play notification sound
--open "https://..." URL to open on click
--execute "open /path" Command to run on click
--group "my-group" Group notifications together

Tip: Combine push with notify: tailstats push abc123 --value "Error" --notify "Build failed!"

Local Push Server

Three ways to push data to TailStats from local scripts and services.

HTTP Server

REST API on localhost for easy integration.

POST http://localhost:9876/push/<card-id>
Content-Type: application/json

{"items": [{"title": "Status", "type": "string", "value": "OK"}]}

WebSocket support available for persistent connections.

Unix Socket

Fastest option for local scripts. Low-latency IPC.

Socket Path ~/tmp/tailstats.sock

The CLI automatically uses Unix socket when available.

File Drop

Drop JSON files to push data. Works offline, no server needed.

Directory ~/Library/Application Support/TailStats/push/

Use tailstats push --file-drop to force file-based delivery.

Protocol Selection: CLI automatically picks the fastest available: Unix Socket → HTTP → File Drop.

File Watch Cards

Monitor local files and display their contents as live cards.

Parsing Modes

Raw Content

Display the entire file contents as text. Good for log files or simple text output.

JSONPath

Extract specific values from JSON files using JSONPath expressions. Same syntax as API extractions.

Items Array

Parse file as TailStats structured response format with items array.

Sandbox-Safe: TailStats uses secure file bookmarks to access files outside the sandbox. You'll be prompted to grant access once per file.

Scripts & Endpoints

Scripts let you write custom JavaScript that returns data in TailStats card format. Each script gets a hosted endpoint URL that you can use as a Remote API data source for your cards — no server required.

How It Works

  1. Write a JavaScript function in the TailStats dashboard
  2. Your script runs on TailStats' edge infrastructure when called
  3. Use the generated endpoint URL as a Remote API card data source
  4. Your card updates automatically at your configured refresh interval

Use cases: Aggregate data from multiple APIs, transform responses into card format, monitor services that don't have a TailStats-compatible API, or build custom integrations with any data source.

Response Format

Scripts must export a default async function that returns a JSON object with an items array:

export default async function() {
  const response = await fetch("https://api.example.com/stats");
  const data = await response.json();

  return {
    items: [
      {
        title: "Active Users",
        type: "number",
        value: data.active_users,
        icon: "person.fill",
        color: "blue"
      },
      {
        title: "Server Status",
        type: "status",
        value: data.healthy ? "Operational" : "Down",
        color: data.healthy ? "green" : "red"
      }
    ],
    columns: 2
  };
}
Field Required Description
items Yes Array of card items (same format as Structured Response)
columns No Number of columns (1–4, default 1)

Scripts can use fetch() to call any external API. All standard card item types are supported — see Card Types for the full list.

Using Endpoints

Each script gets a unique endpoint URL that you can use as a card's data source:

https://userapi.tailstats.com/s/{publicId}

To use a script endpoint in a card:

  1. Copy the endpoint URL from the Scripts dashboard
  2. Create or edit a card and set the data source to Remote API
  3. Paste the endpoint URL
  4. Set authentication to Bearer Token with your API key or script token

Authentication

All script endpoint requests require a Bearer token in the Authorization header:

Authorization: Bearer your-api-key-or-script-token

You can use either your workspace API key or a dedicated script token (see below).

Script Tokens

For fine-grained access control, you can generate a dedicated token for each script instead of using your workspace API key.

Auth Method Scope Best For
API Key All workspace scripts Personal use, your own cards
Script Token Single script only Sharing endpoints, limited access

Generate, regenerate, or revoke script tokens from the script's settings in the dashboard. Tokens are shown once on creation — store them securely.

AI Script Assistant

Describe what you want in plain English and the AI assistant will generate the JavaScript code for you. Available on paid plans.

Example Prompts

  • "Show my GitHub repo star count and latest release"
  • "Fetch Bitcoin and Ethereum prices from CoinGecko"
  • "Check if my website is up and show response time"

Generated code is validated for safety and TailStats compatibility before being suggested. You can refine the output with follow-up prompts.

Plan Limits Beta

Scripts are currently in beta. Limits may increase as the feature matures.

Plan Scripts AI Assistant
Free — —
Starter 3 per workspace Included
Pro 5 per workspace Included
Scale 5 per workspace Included

Rate Limits

Per script: 2 requests per minute