---
title: 'flexkit records'
description: 'List, read, create, update and delete records from the terminal without writing GraphQL.'
---

# `flexkit records`

Reads and writes the records of your project's entities without writing GraphQL. The CLI reads the deployed [schema](/docs/schema) to learn each entity's attributes and scopes, then builds the [GraphQL](/docs/api/graphql) operations for you.

Name an entity by its `name` or its `plural`, as in your schema: `product` and `products` both work.

## Synopsis

```bash
flexkit records <subcommand> <entity> [arguments] [options]
```

## `records ls`

List records of an entity in a table. Without `--fields`, the table shows `_id`, the [display attribute](/docs/schema/entity-reference), up to three more visible attributes and when the record last changed. The newest records come first.

```bash
flexkit records ls <entity> [--where <json>] [--fields <a,b,c>] [--limit <n>] [--offset <n>] [--sort <field[:desc]>] [--scope <scope>] [--json]
```

### Examples

```bash
# List the 20 newest products
flexkit records ls products

# Show chosen columns, cheapest first
flexkit records ls product --fields sku,name,price --sort price

# Only draft products, with German values for scoped attributes
flexkit records ls products --where '{"status":{"eq":"draft"}}' --scope de

# Read the second page of 100 as JSON
flexkit records ls products --limit 100 --offset 100 --json | jq '.[]._id'
```

`--where` takes the generated `<entity>Where` input of the GraphQL API, as JSON, `@file` or `-` for stdin. Filters use nested operators such as `eq`, `in`, `contains`, `startsWith`, `gt` and `lt`; negate with `NOT`:

```bash
# Products whose SKU starts with BAG- and that are not archived
flexkit records ls products --where '{"sku":{"startsWith":"BAG-"},"NOT":{"status":{"eq":"archived"}}}'
```

`--sort` accepts global attributes and `_id`, `_createdAt` and `_updatedAt`, comma-separated, each with an optional `:desc`. Scoped attributes can't be sorted on.

## `records get`

Show one record with every attribute. Relationships are shown as the ids of the linked records and assets as their URLs. Alias: `records inspect`.

```bash
flexkit records get <entity> <id> [--scope <scope>] [--json]
```

### Examples

```bash
# Show a product
flexkit records get product 0c5a7e7b-2f4e-4bb1-9a63-4f1d8c2e9a10

# Show its German values
flexkit records get product 0c5a7e7b-2f4e-4bb1-9a63-4f1d8c2e9a10 --scope de

# Read one value in a script
flexkit records get products prod_bag_001 --json | jq -r '.name.default'
```

With `--json`, a scoped attribute is an object keyed by scope (`{ "default": "Tote", "de": "Tasche" }`), or the value of one scope when you pass `--scope`.

## `records count`

Count the records of an entity, or only those matching `--where`.

```bash
flexkit records count <entity> [--where <json>] [--json]
```

### Examples

```bash
# Count every product
flexkit records count products

# Count products in stock
flexkit records count products --where '{"stock":{"gt":0}}'
```

## `records create`

Create a record from `--data` and `--set` values. A new UUID is used as the id unless the data has an `_id`. Alias: `records add`.

```bash
flexkit records create <entity> [--data <json|@file|->] [--set <key=value>]... [--scope <scope>] [--json]
```

### Examples

```bash
# Create a product from flags
flexkit records create product --set sku=BAG-001 --set name="Canvas bag" --set price=49

# Create a product with values in two scopes, linked to a brand
flexkit records create products --data '{"sku":"BAG-002","name":{"default":"Tote","de":"Tasche"},"brand":"brand_acme"}'

# Create from a file and print the new id
flexkit records create product --data @product.json --json | jq -r '._id'
```

## `records update`

Change attributes of one record. Attributes you don't pass keep their values.

```bash
flexkit records update <entity> <id> [--data <json|@file|->] [--set <key=value>]... [--scope <scope>] [--json]
```

### Examples

```bash
# Change the price of a product
flexkit records update product prod_bag_001 --set price=39.5

# Set only the German name
flexkit records update products prod_bag_001 --set name=Tasche --scope de

# Replace the categories and clear the subtitle
flexkit records update product prod_bag_001 --data '{"categories":["cat_bags","cat_sale"],"subtitle":null}'
```

A list of relationships is replaced by the ids you pass: links that aren't in the list are removed. Fields with 100 or more links are refused, because the CLI reads only the first 100; change those with a [`flexkit query`](/docs/cli/query) mutation that connects or disconnects the links you mean.

## `records rm`

Delete one or more records together with their scoped values. The CLI lists ids it can't find and asks for confirmation before deleting; pass `--yes` in scripts. Aliases: `records remove`, `records delete`.

```bash
flexkit records rm <entity> <id...> [--yes] [--json]
```

### Examples

```bash
# Delete a product
flexkit records rm product prod_bag_001

# Delete several products without a prompt
flexkit records rm products prod_bag_001 prod_bag_002 --yes
```

## Writing values

`--data` takes a JSON object of attribute values, inline, as `@file`, or `-` for stdin. `--set key=value` sets one attribute and can be repeated; values are parsed as JSON when possible (`price=49` is a number, `active=true` a boolean, `'tags=["a","b"]'` a list), and the CLI converts them to the attribute's data type, so `--set sku=123` is still stored as the text `"123"`. `--set` values override the same keys from `--data`.

| Attribute kind                                        | Value                                                                                                                          |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Global                                                | The value: `--set price=49`.                                                                                                   |
| [Scoped](/docs/schema/scopes) (`scope: 'local'`)      | A value for the scope chosen with `--scope` (default: the default scope), or an object keyed by scope: `--set name.de=Tasche`. |
| [Relationship](/docs/schema/relationships-and-scopes) | The id of the linked record, or a list of ids for a multiple relationship. On update, the list replaces the current links.     |
| Asset                                                 | The asset id, or a list of asset ids in display order. Upload files first with [`flexkit assets`](/docs/cli/assets).           |

Pass `null` to clear a value or remove every link. `_id` can be set on create only; `_createdAt` and `_updatedAt` are set by Flexkit.

## Options

| Option                     | Description                                                                     |
| -------------------------- | ------------------------------------------------------------------------------- |
| `--where <json\|@file\|->` | GraphQL filter for `ls` and `count`.                                            |
| `--fields <a,b,c>`         | Columns for `ls`. `_id` is always included.                                     |
| `--limit <n>`              | Maximum number of records for `ls`. Default: 20.                                |
| `--offset <n>`             | Number of records to skip for `ls`. Default: 0.                                 |
| `--sort <field[:desc]>`    | Sort order for `ls`, comma-separated. Default: `_createdAt:desc`.               |
| `--scope <scope>`          | Scope of scoped attributes to show (`ls`, `get`) or write (`create`, `update`). |
| `--data <json\|@file\|->`  | Attribute values for `create` and `update`.                                     |
| `--set <key=value>`        | One attribute value for `create` and `update`. Repeatable.                      |
| `-y`, `--yes`              | Delete without asking for confirmation.                                         |
| `--json`                   | Print the result as JSON on stdout.                                             |
| `-p`, `--project <id>`     | Project to use. Defaults to the [linked project](/docs/cli/link).               |

You can also use all [global options](/docs/cli/global-options).

## Permissions

Your [role and space memberships](/docs/concepts) apply exactly as in Studio: a viewer can list, read and count but can't create, update or delete, and records in spaces you don't belong to are not returned.

The schema is read from the project API, with your `flexkit login` session or a project [API token](/docs/api/tokens).

## Scripting

Every subcommand supports `--json`, prints it on stdout and exits with code `1` on errors, so commands can be chained:

```bash
# Archive every draft product older than the newest 100
flexkit records ls products --where '{"status":{"eq":"draft"}}' --offset 100 --limit 500 --json \
  | jq -r '.[]._id' \
  | xargs -I{} flexkit records update products {} --set status=archived

# Copy a record into a new one with a different SKU
flexkit records get product prod_bag_001 --json \
  | jq 'del(._id, ._createdAt, ._updatedAt) | .sku = "BAG-001-B"' \
  | flexkit records create product --data -
```

Relationship lists are read up to 100 linked records. For bulk changes, larger exports or operations these commands don't cover, use [`flexkit import`](/docs/cli/import), [`flexkit export`](/docs/cli/export) or [`flexkit query`](/docs/cli/query).


---

[View full sitemap](/docs/sitemap.md)