> ## Documentation Index
> Fetch the complete documentation index at: https://trysalty.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> The salty command — workspace and key management from the terminal.

The [Salty](https://trysalty.com) CLI talks to the same REST API as the SDK and MCP server — see [trysalty.com](https://trysalty.com) for the product overview and pricing.

It exists for the bits a human still does once in a while: creating an API key, eyeballing usage, registering a webhook, tailing the call log when a deploy goes sideways.

## Install

```bash theme={null}
npm install -g salty-cli      # global `salty` command
# or run without installing:
npx salty-cli <command>
```

Published on npm (MIT-licensed): **[npmjs.com/package/salty-cli](https://www.npmjs.com/package/salty-cli)**.

## Hosts

Every command takes `--api <url>` or reads `$SALTY_API` from the environment. Defaults: `https://api.trysalty.com`.

## Login

```bash theme={null}
salty login
```

Opens a browser, runs the standard OAuth 2.1 + PKCE flow against `$SALTY_API/oauth/authorize`, and stores the resulting token. Storage prefers the OS keychain (macOS Keychain / Windows Credential Vault / libsecret on Linux); if the keychain isn't available (headless, CI), it falls back to `~/.config/salty/credentials.json` with `0600` perms.

`salty logout` forgets credentials for the current host.

## Identity + usage

```bash theme={null}
salty whoami                          # workspace, plan, period usage
salty usage                           # plan + cap + last 24h breakdown
```

## API keys

```bash theme={null}
salty keys list
salty keys create --name "agent-prod"   # prints sk_live_… ONCE
salty keys revoke <id>
```

## People, companies, deals

```bash theme={null}
salty people list [--limit 50]
salty people get <id>
salty people create --email jane@acme.com --first-name Jane --last-name Doe
salty people search --filter '{"email":{"contains":"@acme.com"}}' [--expand primary_company]

salty companies list
salty companies get <id>
salty companies create --name Acme --domain acme.com
salty companies search --filter '{"domain":{"equals":"acme.com"}}'

salty deals list
salty deals get <id>
salty deals create --name "Big deal" --stage won --value-cents 500000 --currency USD
salty deals search --filter '{"stage":{"equals":"won"}}' --sort '[{"value_cents":"desc"}]'
```

`search` takes a structured `--filter` (JSON): operators `equals | not_equals | contains | gt | gte | lt | lte | is_null`, combined with `{"and":[…]}` / `{"or":[…]}`; address custom attributes via `custom_attributes.<key>`. `--limit`, `--sort`, and `--expand` (people/deals) are also accepted.

`notes`, `tasks`, `activities`, and `custom-objects` follow the same REST shape via the SDK or curl.

## Schema

```bash theme={null}
salty schema show
salty schema add-attribute \
  --object person \
  --key tier \
  --type enum \
  --values "free,pro,enterprise"
```

`--display-name` defaults to a Title-Case version of `--key`.

## Webhooks

```bash theme={null}
salty webhooks list
salty webhooks add --url https://yourapp.com/hooks/salty --events "*"
salty webhooks test <id>              # sync fire, prints HTTP status + body
```

`salty webhooks add` prints the `whsec_…` signing secret once — store it the same way you store an API key.

## Logs

```bash theme={null}
salty logs tail [--limit 200]
```

Dumps the last 100 API calls then polls every 2s for new ones. Ctrl-C exits cleanly.

## JSON output

Every command accepts `--json` to dump the raw response, useful for piping into `jq`:

```bash theme={null}
salty people list --json | jq '.data[] | select(.custom_attributes.tier == "pro")'
```