---
title: CLI quickstart | Lightfield
description: Get started with the Lightfield API using the CLI.
---

The Lightfield API is currently in beta. Methods, parameters, and response schemas may change as we incorporate feedback during this period.

This guide walks you through making your first request to the Lightfield API using the Lightfield CLI.

## Installation

### Homebrew (macOS)

Terminal window

```
brew install Lightfld/lightfield/lightfield
```

**macOS:** The CLI is not yet notarized with Apple. If macOS prevents it from running, allow it in **System Settings → Privacy & Security**, or run:

Terminal window

```
xattr -d com.apple.quarantine /opt/homebrew/bin/lightfield
```

### Go

Requires Go 1.22+.

Terminal window

```
go install github.com/Lightfld/lightfield-cli/cmd/lightfield@latest
```

The binary is placed in your Go bin directory (`$(go env GOPATH)/bin`). If `lightfield` isn’t found, add it to your PATH: `export PATH="$PATH:$(go env GOPATH)/bin"`.

Verify the installation:

Terminal window

```
lightfield --version
```

## Get an API key

An [API key](/using-the-api/api-keys/index.md) can be created in [Lightfield settings](https://crm.lightfield.app/crm/settings/api-keys) (admin only).

When creating the key, select the [scopes](/using-the-api/scopes/index.md) your integration needs.

For the test call just below, you’ll need `accounts:read`.

Set the key as an environment variable so the CLI can use it:

Terminal window

```
export LIGHTFIELD_API_KEY="sk_lf_..."
```

## Make your first request

The CLI follows a `lightfield [resource] [command] [flags]` structure.

[List](/api/resources/account/methods/list/index.md) one account to verify your key and scope:

Terminal window

```
lightfield account list --api-key "$LIGHTFIELD_API_KEY" --limit 1
```

A successful response looks like:

```
{
  "data": [
    {
      "id": "id",
      "createdAt": "createdAt",
      "fields": {
        "foo": {
          "value": "string",
          "valueType": "valueType"
        }
      },
      "httpLink": "httpLink",
      "relationships": {
        "foo": {
          "cardinality": "cardinality",
          "objectType": "objectType",
          "values": [
            "string"
          ]
        }
      }
    }
  ],
  "object": "object",
  "totalCount": 1
}
```

With `--limit 1`, you get at most one account back. To fetch more results, use `--limit` and `--offset`. See [List methods](/using-the-api/list-endpoints/index.md) for pagination.

The CLI does not currently support [list filtering](/using-the-api/list-endpoints#filtering/index.md). To filter results (e.g. `$name[equal]=Acme Corp`), use the HTTP API or one of the SDKs directly.

You can also create records directly from the command line:

Terminal window

```
lightfield account create \
  --api-key "$LIGHTFIELD_API_KEY" \
  --fields '{"$name": "Acme Corp", "$website": ["https://acme.com"]}'
```

Use `--debug` to see the full HTTP request and response, and `--format json` for machine-readable output:

Terminal window

```
lightfield account list --api-key "$LIGHTFIELD_API_KEY" --limit 1 --debug --format json
```

If you get `401 Unauthorized`, check that `LIGHTFIELD_API_KEY` is set correctly. If you get `403 Forbidden`, your key may not have the required scope (e.g. `accounts:read` for listing accounts). For more on error responses and how to handle them, see [Errors](/using-the-api/errors/index.md).

## Global flags

| Flag         | Description                                                     |
| ------------ | --------------------------------------------------------------- |
| `--api-key`  | API key (overrides `LIGHTFIELD_API_KEY`)                        |
| `--base-url` | Custom API base URL                                             |
| `--format`   | Output format: `auto`, `json`, `jsonl`, `pretty`, `raw`, `yaml` |
| `--debug`    | Enable debug logging with full HTTP details                     |
| `--help`     | Show help for any command                                       |

## Next steps

- **[Objects in Lightfield](/objects-in-lightfield/object-types/index.md)** — Overview of object types (accounts, contacts, opportunities, and more) and how they relate.
- **[CLI API Reference](/api/cli/index.md)** — Full API reference with CLI code examples.
- **[Rate limits](/using-the-api/rate-limits/index.md)** — Request limits and how to handle 429 responses.
- **[Idempotency](/using-the-api/idempotency/index.md)** — Safe retries for create and update operations.