---
title: 'flexkit assets'
description: 'Reference and usage guidance for flexkit assets.'
---

# `flexkit assets`

Manage project assets from your terminal: upload files or URLs, and export every asset (files plus metadata) into a portable tarball.

## Synopsis

```bash
flexkit assets upload <path|url> [...] [options]
flexkit assets export [dest.tar.gz] [options]
```

## `flexkit assets upload`

Uploads files, directories or remote URLs as project assets. Each upload is a single request that stores the file and creates the asset record, so the asset `_id` is returned immediately and can be used to link the asset to entity attributes.

### Behavior

- Directories are walked recursively; dotfiles are skipped. Shell globs (`./images/*.png`) work because your shell expands them into file arguments.
- Remote `https://` URLs are downloaded and re-uploaded to the project.
- Identical files are deduplicated by their SHA-256 content hash: re-uploading the same bytes returns the existing asset (`deduped: true`) instead of creating a duplicate. Re-running an upload is therefore safe and cheap.
- The default output is a table with `_id`, filename, size and dedupe status. Use `--json` for machine-readable NDJSON (one asset per line) on stdout.
- Returns a non-zero exit code if any upload fails.

Each created asset includes:

```json
{
  "_id": "6b8f6f0e-...",
  "path": "my-project/x7fKq9.jpg",
  "mimeType": "image/jpeg",
  "originalFilename": "red-chair.jpg",
  "extension": "jpg",
  "size": 48213,
  "width": 1600,
  "height": 1200,
  "lqip": "data:image/jpeg;base64,...",
  "sha256": "9f86d08...",
  "deduped": false
}
```

The `_id` is what you use to connect the asset to an entity attribute through the GraphQL API, and it is also shown in the Studio's Asset Manager (row actions → Copy ID).

### Options

- `--project <ID>`: Select the project when the local config defines several.
- `--concurrency <N>`: Number of parallel uploads (default `5`).
- `--id-from <STRATEGY>`: Derive deterministic asset `_id`s instead of random UUIDs. `filename` uses the file name without its extension; `hash` uses the SHA-256 hex digest of the file content. Deterministic ids make imports idempotent and let you reference assets predictably.
- `--tag <NAME>`: After uploading, tag every uploaded asset with the given tag. The tag is created if it does not exist.
- `--json`: Print created assets as NDJSON on stdout.

### Examples

```bash
# Upload a folder of images
flexkit assets upload ./images

# Upload specific files and a remote URL, tagging them
flexkit assets upload hero.png https://example.com/logo.svg --tag branding

# Deterministic ids derived from filenames, NDJSON output
flexkit assets upload ./icons --id-from filename --json > uploaded.ndjson
```

## `flexkit assets export`

Exports project assets into a `.tar.gz` bundle containing the binary files and their metadata.

### Behavior

- Queries all assets (paginated), downloads every file, and writes a tarball with:
  - `assets.ndjson` — one asset per line with full metadata (`_id`, `path`, `mimeType`, `originalFilename`, `extension`, `size`, `width`, `height`, `lqip`, `sha256`, `tags`) plus a `_file` field pointing at the bundled binary.
  - `files/<id>.<ext>` — the binary files.
- The default destination is `flexkit-assets-<projectId>-<date>.tar.gz` in the current directory.
- The bundle round-trips: `flexkit import <bundle.tar.gz>` re-uploads every asset preserving its `_id` and tags (content deduplication makes this idempotent).

### Options

- `--project <ID>`: Select the project when the local config defines several.
- `--tag <NAME>`: Only export assets with the given tag.
- `--concurrency <N>`: Number of parallel downloads (default `5`).
- `--overwrite`: Replace the destination file if it already exists.

### Examples

```bash
# Export all assets
flexkit assets export

# Export only tagged assets to a specific file
flexkit assets export branding.tar.gz --tag branding

# Move assets to another project
flexkit assets export all-assets.tar.gz
flexkit import all-assets.tar.gz --project other-project
```


---

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