# Blocklive CLI

Source: https://blocklive.io/docs/developers/cli

Use Blocklive from your terminal, signed in as yourself, with only what your
roles allow. List your events, check one event's sales and check-ins, and
export its guests, by hand or from a script.

> **Note:** The CLI reads. It doesn't change anything yet: anything that
> deletes, cancels, refunds or pays out stays on blocklive.io, and the CLI
> prints the link to the event's page.

## What you can do

| Task                                  | Command                                      |
| ------------------------------------- | -------------------------------------------- |
| Sign in through your browser          | `blocklive login`                            |
| See who you're signed in as           | `blocklive whoami`                           |
| List the events you can see           | `blocklive events list`                      |
| See an event's sales and check-ins    | `blocklive event show summer-opening`        |
| List an event's guests                | `blocklive guests list summer-opening --all` |
| Get any of these as JSON for a script | add `--json`                                 |
| Sign out, here and on Blocklive       | `blocklive logout`                           |

Every command is described in [commands](https://blocklive.io/docs/developers/cli/commands); JSON, errors and
exit codes are in [scripts and errors](https://blocklive.io/docs/developers/cli/scripts).

## Install

The CLI needs [Node.js](https://nodejs.org) 20 or later. Check with
`node --version`, then install the CLI from npm:

```sh
npm install --global @blocklive/cli
```

```sh
blocklive --version
```

Or run it once without installing:

```sh
npx @blocklive/cli login
```

> **Note:** The CLI is new. If npm can't find `@blocklive/cli`, it isn't
> published yet: email [support@blocklive.io](mailto:support@blocklive.io) to
> join the pilot.

To check that the package you installed is the one Blocklive published, ask
npm to verify its registry signatures:

```sh
npm audit signatures
```

To update, run the install command again. When your version is too old to
talk to Blocklive, every command stops with `upgrade_required` and the
command to run.

## Quick start

You need a Blocklive account with a role at a team, event or organization, and
two-step verification turned on (see
[two-step verification](https://blocklive.io/docs/account/sign-in#two-step-verification)).

**1. Sign in.** The terminal prints a code; open
[blocklive.io/cli](https://blocklive.io/cli), enter it, and approve.

```sh
blocklive login
```

**2. List your events** and note the slug of the one you want.

```sh
blocklive events list
```

**3. See how it's selling.**

```sh
blocklive event show summer-opening
```

**4. Export its guests' emails** (managers and admins).

```sh
blocklive guests list summer-opening --all --json | jq -r '.guests[].email'
```

Signing in step by step, and what you choose when you approve, are in
[signing in](https://blocklive.io/docs/developers/cli/sign-in).

## How it works

-   **You sign in through your browser.** `blocklive login` asks Blocklive for a
    one-time code. You type it at blocklive.io/cli, where you're signed in and
    confirm two-step verification, and approve what the CLI may do. The CLI
    never sees your password or email code. (This is the "device sign-in"
    many command-line tools use.)
-   **It acts as you, never more.** Each request is checked again on
    Blocklive: your account, your roles at the places you approved, and the
    limits. Lose a role and the CLI loses it at the same moment.
-   **Its sign-in is short-lived.** Access lasts 15 minutes and is renewed
    automatically; the sign-in itself ends after 12 hours at most, sooner if
    unused. See [how long a sign-in lasts](https://blocklive.io/docs/developers/cli/sign-in#how-long-a-sign-in-lasts).
-   **The sign-in is kept in your keychain**, not in a file or an environment
    variable. See
    [where the sign-in is kept](https://blocklive.io/docs/developers/cli/sign-in#where-the-sign-in-is-kept).
-   **It talks only to Blocklive over HTTPS.** The CLI's own connection to
    Blocklive isn't a public API and changes with the CLI. To build your own
    app, use the [developer API](https://blocklive.io/docs/developers) with an API key.

## CLI or developer API?

|                 | Blocklive CLI                               | Developer API                               |
| --------------- | ------------------------------------------- | ------------------------------------------- |
| Who it's for    | You, at a terminal or in your own scripts.  | An app or a server: a door app, a CRM sync. |
| Signs in as     | You, with your roles.                       | An API key an organizer made.               |
| Lasts           | Up to 12 hours, then sign in again.         | Until the key is revoked or expires.        |
| Guests' details | What your role shows on the Attendees page. | Only the details shared with the key.       |

## Help

Email [support@blocklive.io](mailto:support@blocklive.io) with the
`request_id` of any error.