# Command line

`uselayer` calls the [API](https://uselayer.sh/docs/api.md) with your key, so you can try Layer from a terminal before writing any code.

Every command says which Layer it's calling, ends with ✓ or ✗, and suggests the next command to run. When the API turns a request down, the reason and how to fix it are printed under the ✗.

## Install

You need Node 18.17 or later. Check with `node -v`; if it's missing or older, get it from [nodejs.org](https://nodejs.org).

There are two ways to run `uselayer`. Pick one:

| | Run with npx | Install it once |
|---|---|---|
| Command | `npx uselayer login` | `npm install -g uselayer`, then `uselayer login` |
| What it does | Downloads `uselayer` and runs it, without adding a `uselayer` command to your terminal. | Installs it for your whole computer (`-g` means global), so `uselayer` works in any folder. |
| Good for | Trying Layer, or a one-off check. | Using it every day. |
| Every command starts with | `npx uselayer …` | `uselayer …` |

With npx, keep typing `npx uselayer` each time: a bare `uselayer` gives `command not found`. The CLI knows how you started it, so the next command it suggests is always one you can paste as-is.

Check it's working with `uselayer --version` (or `npx uselayer --version`).

```bash
npx uselayer login          # paste your key from the dashboard
npx uselayer matches --q nfl
```

### If something goes wrong

| What you see | Why | Fix |
|---|---|---|
| `zsh: command not found: uselayer` (or `bash: …`) | You ran it with npx, which doesn't install a command. Or it's installed globally, but npm's folder for global commands isn't on your `PATH`. | Use `npx uselayer …`, or run `npm install -g uselayer`. If it's installed and still not found, run `npm prefix -g`, add the `bin` folder inside it to your `PATH`, then open a new terminal. |
| `404 Not Found - GET https://registry.npmjs.org/uselayer.` | The package name was typed with something extra: here, a full stop at the end. | Type exactly `uselayer`: `npm install -g uselayer`. |
| `EACCES: permission denied` during `npm install -g` | npm's global folder belongs to another user on your computer. | Use `npx uselayer …` instead, or install Node with a version manager such as [nvm](https://github.com/nvm-sh/nvm), which keeps global installs in your own folder. Avoid `sudo npm install -g`. |
| `npm warn EBADENGINE Unsupported engine`, or a `SyntaxError` when it starts | Node is older than 18. | Update Node, then run the command again. |

- **Update:** `npm install -g uselayer@latest`. npx can reuse a copy it downloaded earlier; `npx uselayer@latest …` makes it fetch the newest.
- **Uninstall:** run `uselayer logout` first if you want your saved key removed too, then `npm uninstall -g uselayer`.

## Your key

`uselayer login` asks for your key from the [dashboard](https://uselayer.sh/dashboard), checks it with Layer, and saves it in `~/.config/uselayer/config.json`, readable only by you. You can also pass it: `uselayer login lyr_your_key`, or `echo $LAYER_KEY | uselayer login`. `uselayer logout` forgets it.

If `LAYER_KEY` is set in your environment, it's used instead of the saved key, so scripts and CI don't need a login.

## Commands

| Command | What it does |
|---|---|
| `uselayer matches [--q nfl] [--from 2026-10-03] [--to 2026-10-05] [--category sports] [--venue polymarket-us\|polymarket] [--limit 50] [--offset 0]` | Live matches, soonest event first, as in `GET /v0/matches`: with Polymarket US, or polymarket.com with `--venue polymarket`. Each one shows both markets' ids and who checked the match. |
| `uselayer match <market id> [--venue kalshi\|polymarket\|polymarket-us] [--with polymarket]` | The same market on the other venue, as in `GET /v0/match`, with both venue links. Leave `--venue` out and it's read from the id: an upper-case ticker is Kalshi, a `:long` or `:short` side is Polymarket US, and anything else is polymarket.com. A Kalshi market's twin is looked up on Polymarket US; `--with polymarket` looks on polymarket.com. When there's no twin, it says why. |
| `uselayer profit --match KXFEDDECISION-26OCT-C25 --contracts 100 --kalshi 0.42 --polymarket 0.55` | Buy one side on Kalshi and the other on Polymarket at these prices: the profit after both venues' fees, as in `POST /v0/profit`. `--match` is the match's Kalshi ticker: Layer fills in both markets' fees and how long your money is held, and says which it filled in. Use `--polymarket-us 0.55` for Polymarket US instead. The check runs on Layer from the prices you give it; Layer doesn't fetch venue prices for you. |
| `uselayer login [key]`, `uselayer logout` | Save or forget your key. |
| `uselayer help` | All of the above. Add `--help` to any command for its options. |

### profit options

| Option | Meaning |
|---|---|
| `--contracts` | Contracts bought on each venue. |
| `--kalshi`, `--polymarket`, `--polymarket-us` | The price you pay on each venue, in dollars (`0.42` is 42¢). Send `--kalshi` and one of the other two. |
| `--match` | The Kalshi ticker of a live match. Layer fills in every fee and `--days` you leave out; anything you pass yourself is used instead. |
| `--category` or `--fee-rate` | Polymarket's fee: the category's default rate, or the market's own `feeSchedule.rate`. One is needed with `--polymarket` unless you send `--match`. `--exponent` sets `feeSchedule.exponent`. |
| `--fee-coefficient` | Polymarket US's fee (`0.095` by default: the rate its markets report, which takers under $10K of trailing 30-day volume pay). |
| `--fee-multiplier`, `--fee-type` | The Kalshi series' `fee_multiplier` and `fee_type`. |
| `--kalshi-role`, `--poly-role` | `maker` if your order rests on the book first (`taker` by default). |
| `--settles-at 2026-10-04` or `--days 4` | When the money comes back; adds return per day. |

## For scripts

Add `--json` to any command and it prints only the API's JSON answer, the same as calling the API directly. A failed call prints the API's error JSON and exits with status 1.

```bash
uselayer matches --q nfl --json | jq -r '.matches[].kalshi.market_id'
```

`--local` calls a Layer running on `http://localhost:3100` instead of `https://uselayer.sh`; `LAYER_API_URL` points it anywhere else.
