CLI quickstart

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)

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:

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

Go

Requires Go 1.22+.

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:

lightfield --version

Get an API key

An API key can be created in Lightfield settings (admin only).

When creating the key, select the scopes 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:

export LIGHTFIELD_API_KEY="sk_lf_..."

Make your first request

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

List one account to verify your key and scope:

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 for pagination.

The CLI does not currently support list filtering. 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:

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:

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.

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 — Overview of object types (accounts, contacts, opportunities, and more) and how they relate.
• CLI API Reference — Full API reference with CLI code examples.
• Rate limits — Request limits and how to handle 429 responses.
• Idempotency — Safe retries for create and update operations.