# 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.

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](/docs/api) is a command of two words, a resource and a verb:

```bash
clearsaga sites list
clearsaga funnels create
```

The commands are produced from the same list of operations as the API and the [MCP server](/docs/mcp), 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](/docs/status) 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:

```bash
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.

## Sign in

Create a token first, under Settings, Agent access. [Connect an AI agent](/docs/agents) explains the permissions. Then run:

```bash
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.

## Environment variables in place of login

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

```bash
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

```bash
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](/docs/api/store) 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](/docs/api#filters). |
| `--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

```bash
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](/docs/agents) lists it):

```bash
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](/docs/agents), [API reference](/docs/api), [Alerts and webhooks](/docs/alerts-and-webhooks)