Agents and API

Command line

Read your numbers and manage funnels, goals and more from a terminal or a script: install the tool, sign in with a token and run commands.

View as Markdown

This page shows how to install the clearsaga command, sign in with a workspace token and run every operation of the API from a terminal or a script. It is written for someone who is comfortable in a terminal.

What it is #

The command line tool is one file with no dependencies. It needs Node 22.4 or newer. Every operation of the API reference is a command of two words, a resource and a verb:

clearsaga sites list
clearsaga funnels create

The commands are produced from the same list of operations as the API and the MCP server, so the three always offer the same things. The tool turns what you type into a request, sends it with your token and prints the answer as JSON. It does not check your values itself: the server does, and the tool prints what the server says.

Install it from the file #

The tool is not published to npm, so it cannot be installed by name. What works today lists this with the other missing parts. For now it is installed from a package file that is built from the source code of Clear Saga.

In a copy of the source code, build the file and install it:

pnpm cli:pack
npm install -g ./cli/clearsaga-cli-0.1.0.tgz
clearsaga --help

The first line builds the tool and leaves a .tgz file in the cli folder. The second installs that file on your computer. The file can be copied to another computer and installed there in the same way.

Create a token first, under Settings, Agent access. Connect an AI agent explains the permissions. Then run:

clearsaga login

It asks for two things: the address of your dashboard, such as https://clearsaga.com, and the token. The token is not shown as you type or paste it. The tool then checks that the token works and only saves it if it does.

Command	What it does
`clearsaga login`	Saves the address and the token.
`clearsaga whoami`	Shows the workspace the token belongs to.
`clearsaga logout`	Deletes what `login` saved.

The address and the token are kept in one file that only your user account can read:

macOS and Linux: ~/.config/clearsaga/config.json, or under $XDG_CONFIG_HOME when that is set.
Windows: config.json in a folder named clearsaga under %APPDATA%.

logout deletes that file. It does not end the token. To do that, revoke the token under Settings, Agent access.

In a script or a scheduled job, skip login and set two environment variables:

export CLEARSAGA_API_URL=https://clearsaga.com
export CLEARSAGA_TOKEN=clearsaga_pat_...

The variables are read first, and the saved file second.

A token is never given as a flag. The list of running programs and the history of your shell would both keep it. If you try, the tool refuses and says so.

The saved token belongs to one address #

The saved token is sent only to the address it was saved with. If you name another address, with the --api flag or with CLEARSAGA_API_URL, the tool does not use the saved token. It uses CLEARSAGA_TOKEN when that is set, and stops with a message when it is not.

This protects you from a command copied from somewhere else: a command that points at a stranger's address cannot carry your token there. For the same reason the tool never follows a redirect, and it accepts an address that starts with http:// only for your own computer.

Run commands #

clearsaga sites list --pretty
clearsaga overview kpis --site site_abc123def456 --range 7d --filter country=us --filter path.has=pricing
clearsaga funnels create --site site_abc123def456 --name "Checkout" \
  --steps-json '[{"type":"pageview","value":"/pricing"},{"type":"event","value":"signup"}]'

Site ids come from clearsaga sites list. The ids above are made up. The store reports work the same way: clearsaga store summary --site <id> --model last_click prints the Store summary, and the store reference lists the rest.

You type	What it means
`--site <id>`	The site the command is about.
`--name "Checkout"`	A field that holds text or a number is a flag with the name of the field.
`--enabled` or `--no-enabled`	A field that is yes or no.
`--filter key=value`	One filter. Repeat the flag for more. The keys are those of the API reference.
`--steps-json '<json>'`	A field that holds a list or an object: the name of the field, then `-json`, then the value as JSON.
`--input '<json object>'`	The whole input at once. Other flags are merged on top.
`--pretty`	Indents the answer so it is easier to read.
`--quiet`	Prints nothing when the command worked.
`--api <address>`	Calls this address in place of the saved one.

The answer is the JSON of the operation, on standard output. Messages and refusals go to standard error, so a script can keep the two apart.

Get help #

clearsaga help
clearsaga funnels
clearsaga help funnels create

The first lists every command. The second lists the verbs of one resource. The third describes one command with every flag it takes, and says whether it needs the Read or the Write permission.

Deleting #

With a token that has Write, a delete command removes what that permission covers (Connect an AI agent lists it):

clearsaga funnels delete --site site_abc123def456 --id fnl_abc123def456

It removes at once, without asking, and it cannot be undone. The answer says what was removed. When the site had nothing with that id, the answer says "deleted": false and the command still ends without an error.

Exit codes #

Every command ends with a code that a script can test.

Code	Meaning
0	Done.
1	The request was refused or failed. The message is on standard error. For an input that was refused, each field is listed.
2	No working token. Run `clearsaga login`.
3	The dashboards of the workspace are locked by its plan.
4	Too many requests. The message says how long to wait.

Values in answers #

Paths, referrers, campaign tags, event names and event properties were sent by the visitors of your site. If you feed the output of a command to an AI agent or to another program, treat those values as data, never as instructions.

Next: Connect an AI agent, API reference, Alerts and webhooks