Freckle

View saved version →

---
name: freckle
description: "Use when the user asks to use the Freckle CLI or get Freckle to do something: enrich/score/process a lead list, build a company or people list, import CRM records, monitor Dataset Signals, build or change Workbooks, datasets, or Workflows, publish or run saved workflows, inspect credit usage or node capabilities, auth/org/config setup, or integration connections."
---

# Freckle

This is a router skill: pick one primary route below and load adjunct references only when that route requires them. Load the route's file before running any `freckle` command — even `--help`; the route files tell you which commands to run and when.

**New builds are gated.** Route work with no existing target to [BUILD.md](BUILD.md). When the request identifies an existing Workbook or Workflow by URL, id, or name, route to [REFINE.md](REFINE.md) instead: locate the target, derive its org, and work from the design already embodied there. REFINE owns the fit test and escalates only a genuine redesign or a shape-changing ambiguity.

## Route

| User wants | Load |
| --- | --- |
| List building — build a new list of companies or people from a provider search, or run/inspect a List Workbook created by the `list` commands | [LIST.md](LIST.md), then selected command help; provider references on demand |
| Import a CSV or plain rows into a **new** Workbook, with no enrichment or workflow asked for and no existing target named | [BUILD.md#data-import-fast-lane](BUILD.md#data-import-fast-lane) — a pure import that names an existing Workbook or Dataset routes to [REFINE.md](REFINE.md) instead |
| Get Freckle to do something with no existing target — enrich, score, look up, run data, or build a Workbook or Workflow | [BUILD.md](BUILD.md) |
| Do anything to an existing Workbook or Workflow identified by URL, id, or name — add data, run rows, or change its setup | [REFINE.md](REFINE.md) |
| Run an existing saved Workflow directly with JSON inputs, inspect runs, list saved Workflows | [workflow/cli-reference.md](workflow/cli-reference.md) |
| Inspect node capabilities | [workflow/cli-reference.md#node-catalog](workflow/cli-reference.md#node-catalog) |
| Workbook housekeeping that changes nothing about what runs — inspect, archive, delete entries, rotate webhook secrets | [WORKBOOKS.md](WORKBOOKS.md) |
| Return a Dataset webhook endpoint URL | [WORKBOOKS.md](WORKBOOKS.md) |
| Create, inspect, list, turn monitoring on or off, or delete Dataset Signals | [SIGNALS.md](SIGNALS.md) |
| Check the current credit balance or report credit usage by Workbook, Workflow, or billed node | [CREDITS.md](CREDITS.md) |
| Log in, check auth, choose org, inspect endpoints | [SETUP.md](SETUP.md) |
| Connect Apify, ContactOut, HeyReach, HubSpot, Instantly, Lemlist, OpenAI, Salesforce, Slack, Supabase, or Twain, or find credential IDs | [CONNECTIONS.md](CONNECTIONS.md) |
| Set up, list, or pick a credential so Workflows can use the user's own API key — match supported provider BYOK first, then custom HTTP APIs; a build or change request that mentions their own key still routes to BUILD or REFINE | [CONNECTIONS.md](CONNECTIONS.md) |
| Understand enrichment waterfalls, collectors, or Research Agent usage | [workflow/waterfall.md](workflow/waterfall.md), [workflow/collector.md](workflow/collector.md), [workflow/research-agent.md](workflow/research-agent.md) |
| Explain what Freckle can currently do — a capability question only, with no task attached | [WHAT-CAN-FRECKLE-DO.md](WHAT-CAN-FRECKLE-DO.md) |

## Shared Operating Rules

- When user decisions are needed, run a **batch grill**. Map the decisions as a design tree and work it in rounds. The frontier is every decision whose prerequisites are settled: ask the whole frontier in one round, number every question, and give your recommended answer for each, then wait for the user's answers. A decision that depends on another unsettled answer waits for a later round. After each reply, recompute the frontier. The grill is complete only when the frontier is empty: every shape-changing branch has been visited and nothing remains silently assumed. Make changes or run data only after the user confirms shared understanding; a route's later approval gate may supply that confirmation.
- Every question round and every plan opens with a **what-will-run summary**: two or three plain sentences saying what Freckle will do once the user says go — which rows it reads, what happens to each, where results land, and what it costs — in product words only, with no flag names, node keys, or field paths. The tables, diagrams, and commands that follow are evidence for the summary, never a substitute for it.
- Facts are agent work. Resolve anything available from the CLI, filesystem, inspected artifacts, catalogs, or other tools instead of asking the user. If a lookup can run independently, dispatch it and ask the rest of the frontier while it runs; only decisions downstream of that lookup wait.
- Names are agent work too. Choose the label for every new Workbook, Dataset, and Workflow yourself — short, descriptive, in the user's own words for the goal — and show it wherever the user meets the artifact: the what-will-run summary, the plan, and the final link. Use a name the user supplies verbatim; otherwise the user renames in the app if they prefer something else.
- Resolve the org from any named resource before asking the user. Confirm the active org only when the request supplies no resource from which to derive it. Auth-only, config-only, and generic product-capability answers need no org setup.
- After automatic resolution, user selection, or an explicitly supplied organization, append `--org-id=<org-id>` after the complete subcommand path of every subsequent CLI command — for example, `freckle workbook list --org-id=<org-id>` — preserving any organization the user supplied. Do not use `freckle org switch`; it writes shared global config that another agent can overwrite.
- Preflight before the first command: `command -v freckle && freckle whoami`.
- `--json` always means output: structured results render YAML by default and pretty JSON with `--json`. Commands that support tables require `--table`. Generic inline JSON payloads use `--input-json`; command help documents specialized JSON filters and file inputs.
- Confirm unfamiliar flags with `freckle <subcommand> --help` before running a command your route file prescribes.
- Use absolute `--file` paths when possible; package scripts can change relative resolution.

Referenced files: 27

View saved version →

---
name: setup
description: Freckle setup — install and authenticate the `freckle` CLI, which is how the plugin talks to Freckle. Use when `freckle` is not found on PATH or the `freckle` found on PATH is the wrong version, `freckle auth status` fails, the CLI isn't signed in, or the user wants to configure Freckle. Signs the user in for new users.
allowed-tools: Bash, Read, Edit, Write
---

# Freckle setup

Skills reach Freckle through the **`freckle` CLI**. **`freckle auth`** runs a device flow once
and stores the credential on disk; the CLI re-reads it on every command, so `freckle auth status`
succeeding is the whole proof.

## 1. Check current state

Run this and read the printed **exit code and output**, not any status string:

```bash
freckle auth status; echo "exit_code=$?"
```

- **exit_code=0** and the output shows a signed-in identity → the CLI is authenticated.
  Also confirm it isn't an old install shadowing the bundled launcher, which an
  auth check alone can't tell you — compare the resolved version against the
  release this plugin pins in `bin/cli-version` (two levels up from this skill's
  directory):

  ```bash
  # Prints e.g. `freckle v1.0.0`; compare the semver part.
  freckle --version
  # The pin is a full release tag like cli-v1.0.0-r299-3b81ee5; extract its semver.
  sed -e 's/^cli-v//' -e 's/-r.*//' "<THIS_SKILL_DIR>/../../bin/cli-version"
  ```

  - **same version, or newer than the pin** → the CLI is current. Tell the user
    (name the signed-in identity) and stop.
  - **older than the pin** → an outdated `freckle` is shadowing the bundled
    launcher. Do step 2 to put the launcher ahead of it on PATH, then re-run
    this check.

- **`freckle: command not found`** (or exit 127) → the CLI isn't on your PATH.
  Route by platform:
  - **Claude Code**: if the plugin was just installed in this session, this is expected —
    Claude Code only adds a newly installed plugin's `bin/` to PATH starting with the
    _next_ session. Don't install a forwarder for this: resolve the bundled launcher's
    absolute path once and invoke that directly for the rest of this session instead of
    waiting on a restart —

    ```bash
    launcher="$(sh -c 'ls -1dt "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/freckle/*/bin/freckle 2>/dev/null | head -n1')"
    [ -x "$launcher" ] || { echo "could not locate the bundled freckle launcher; reinstall the plugin"; exit 1; }
    "$launcher" auth status; echo "exit_code=$?"
    ```

    Use this same resolved path in place of bare `freckle` for every remaining command in
    this skill (step 3's `freckle auth` included) — but re-run the `ls -1dt` one-liner
    fresh immediately before each one rather than reusing `$launcher` across separate tool
    calls: each Bash call starts a new shell, so a variable set in one call is gone in
    the next. Bare `freckle` starts working again on its own once the agent is next
    restarted, so no restart is needed just for PATH. Only fall back to step 2's
    forwarder if the launcher can't be located at all (e.g. the plugin cache is gone),
    if another `freckle` install is shadowing the bundled one after a restart, or if
    bare `freckle` is still not found after a restart — that last case means the
    next-session auto-PATH isn't happening, so this is no longer a one-restart hiccup
    the launcher path can paper over.

  - **Codex**: go straight to step 2, then step 3 — Codex does not add a plugin's
    `bin/` to PATH automatically, so restarting alone won't fix this.

- **Any other nonzero exit** with output saying the CLI isn't authenticated → the CLI
  works but isn't signed in. Skip to step 3.
- **Network errors** → check the network and any `HTTP_API_ORIGIN` override; do not
  restart the sign-in flow.

## 2. Put `freckle` on your PATH (if it was "command not found" or is an outdated version)

The plugin bundles the CLI launcher at `bin/freckle` in the plugin root; it downloads
and checksum-verifies the real binary on first use. The launcher is version-stable
(it reads its neighbor `bin/cli-version` and fetches that release), so the forwarder
just needs to point at the newest launcher on disk.

Install a small forwarder onto your PATH (in `~/.local/bin`) that resolves the
newest bundled launcher **at runtime** rather than baking in one absolute path.
This is what lets it survive plugin updates (which install a new version directory)
and work no matter which agent (Claude Code / Codex) installed the plugin. It picks
the most-recently-modified launcher; if one agent's cache lags behind another's, the
freshest install wins — every launcher is self-contained, so it still runs a valid
checksum-verified CLI.

First confirm a launcher actually exists where the forwarder will look — this is
the same resolution the forwarder performs, run once now so a missing plugin
cache fails loudly here instead of as a confusing 127 later (run it through `sh`
so unmatched globs stay harmless even if your shell is zsh):

```bash
sh -c 'ls -1dt \
  "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/freckle/*/bin/freckle \
  "${CODEX_HOME:-$HOME/.codex}"/plugins/cache/*/freckle/*/bin/freckle \
  2>/dev/null | head -n1'
```

If this prints nothing, **stop** — no bundled launcher exists in any known plugin
cache, so the forwarder below would have nothing to exec. Tell the user to
reinstall the Freckle plugin, then re-run this skill. (If you read this SKILL.md
from a plugin root outside these caches, report that path to the user — the
plugin is installed somewhere this forwarder doesn't search.)

If it printed a path, install the forwarder (keep its search list in sync with
the pre-flight above and with step 1's Claude Code one-liner):

```bash
mkdir -p "$HOME/.local/bin"
cat > "$HOME/.local/bin/freckle" <<'EOF'
#!/bin/sh
# Resolve the newest bundled freckle launcher at runtime so this forwarder
# survives plugin version bumps and works whichever agent (Claude Code / Codex)
# installed it. CLAUDE_CONFIG_DIR and CODEX_HOME relocate those agents' state
# roots (and with them the plugin cache), so honor them when set — they expand
# here at runtime, from the invoking process's environment.
launcher="$(ls -1dt \
  "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/freckle/*/bin/freckle \
  "${CODEX_HOME:-$HOME/.codex}"/plugins/cache/*/freckle/*/bin/freckle \
  2>/dev/null | head -n1)"
if [ -z "$launcher" ] || [ ! -x "$launcher" ]; then
  printf 'Error: %s\n' 'freckle: no bundled launcher found (reinstall the Freckle plugin)' >&2
  exit 127
fi
exec "$launcher" "$@"
EOF
chmod +x "$HOME/.local/bin/freckle"
```

Then make sure `~/.local/bin` is on PATH (most shells already have it):

```bash
case ":$PATH:" in *":$HOME/.local/bin:"*) echo "on PATH" ;; *) echo "not on PATH" ;; esac
```

If it prints `not on PATH`, add `export PATH="$HOME/.local/bin:$PATH"` to the
user's shell profile (`~/.zshrc` or `~/.bashrc`) and use the absolute path
`"$HOME/.local/bin/freckle"` for the rest of this session.

Re-run the step 1 check before continuing.

> **Alternative — full install.** The standalone installer
> `sh -c "$(curl -fsSL https://install.freckle.io)"` installs the CLI directly to
> `~/.local/bin` with self-update enabled and also sets up agent skills outside
> this plugin. Use it when the user wants Freckle available outside plugin-managed
> agents; the plugin works with either.

## 3. Sign in

`freckle auth` is a device flow you run on the user's behalf. It opens the approval
page in the user's browser, prints a short one-time user code, and waits up to 15
minutes for approval. The credential lands directly in the CLI's local config; nothing
sensitive crosses the terminal or the conversation, and the user code itself is not a
secret — show it to the user so they can match it in the browser.

```bash
freckle auth
```

While the command waits, tell the user to approve the request in the opened browser
tab — signing in or creating an account there first is part of the same flow, and if
no browser opened, the printed URL gets them there. The command exits 0 once approved;
confirm with `freckle auth status`.

When device authorization is unavailable or there is no browser (headless or remote
shells), the user creates a token at https://next.freckle.io/cli-auth and you run:

```bash
freckle auth --token <frk_token>
```

Auth also resolves from `FRECKLE_CLI_TOKEN`.

## 4. Done

Re-run the step 1 check to confirm, tell the user who is signed in, and continue with
whatever task brought you here — the `freckle` skill routes all Freckle work.