Skip to content

The VS Code of video editing, built for agents.

TypeScript

Enhance asset management commands in CLI by introducing `dapi asset ls [ids...]` for listing raw asset records and `dapi asset tree` for displaying the asset library as a folder tree. Updated related types and functions to support these changes, ensuring improved flexibility and clarity in asset handling. Adjusted documentation to reflect new command structures and behaviors.

konstantin-paulus28f71e565c81
diff --git a/apps/cli/api-spec.md b/apps/cli/api-spec.md
index aa110ad8..0d6d19cf 100644
--- a/apps/cli/api-spec.md
+++ b/apps/cli/api-spec.md
@@ -447,9 +447,23 @@ Adds one or more local files as assets in the open project.
---
-### `dapi asset ls`
+### `dapi asset ls [ids...]`
-Lists the asset library of the open project as its folder tree — folders and assets interleaved in one array, each folder carrying its contents in `children`. Aliases: `list`, `get`.
+The raw asset records, as persisted minus the file handles — every serializable property the asset carries (per-type media metadata, `folderId`, a stored `transcript`, …). The property-level counterpart to `asset tree`'s structure. With no ids, returns every asset in the library. Alias: `get`.
+
+- **Input:** `[ids...]` — zero or more asset ids (optional)
+- **Output:** JSON Lines, one per asset
+ ```ts
+ AssetRecord = { id: string } & { [property: string]: unknown }
+ // e.g. name, type, mimeType, size, createdAt, folderId; duration/width/height/… by type
+ ```
+- **Errors:** if any input id fails to resolve, writes a per-id message to stderr and exits non-zero after emitting all successful records to stdout.
+
+---
+
+### `dapi asset tree`
+
+Prints the asset library of the open project as its folder tree — folders and assets interleaved in one array, each folder carrying its contents in `children`.
- **Input:**
- `--folder <id>` — folder whose contents to list (optional; default the library root)
@@ -598,7 +612,7 @@ Decodes one or more frames of a video asset at the given times and writes each t
## Folders
-All under `dapi folder` (alias `dapi fld`). Operate on the open project. Folders organize the asset library and nest arbitrarily; assets reference their containing folder via `folderId` (`null` = library root). Everywhere a folder id is optional, omitting it means the library root — there is no sentinel value for the root. Read the full hierarchy (folders and assets together) with [`asset ls`](#dapi-asset-ls); move assets between folders with [`asset mv`](#dapi-asset-mv-ids---to-folderid).
+All under `dapi folder` (alias `dapi fld`). Operate on the open project. Folders organize the asset library and nest arbitrarily; assets reference their containing folder via `folderId` (`null` = library root). Everywhere a folder id is optional, omitting it means the library root — there is no sentinel value for the root. Read the full hierarchy (folders and assets together) with [`asset tree`](#dapi-asset-tree); move assets between folders with [`asset mv`](#dapi-asset-mv-ids---to-folderid).
### `dapi folder ls [parentId]`
@@ -735,7 +749,7 @@ Lists local fonts available on this machine. macOS only.
## Conventions
-- **Stdout:** JSON. Commands that return a single record emit one JSON value. Commands that return a collection emit JSON Lines (one JSON object per line, no surrounding array) so per-item results stay streamable — this covers list reads (`selection ls`, `selection focus`, `node ls`, `node grep`, `asset ls`, `folder ls`, `models`, `voices`, `fonts`), selection mutations that return the new state, and batch operations (`node rm`, `node patch`, `node cp`, `asset add`, `asset rm`, `asset mv`, `asset export`, `folder mv`, `folder rm`). `node tree` emits one nested JSON object per root, and `asset ls` emits one nested object per root entry. Exceptions: `open` for file / URL / no-target writes nothing; `fonts --names-only` writes plain family names; `mount` and `node insert` write nothing.
+- **Stdout:** JSON. Commands that return a single record emit one JSON value. Commands that return a collection emit JSON Lines (one JSON object per line, no surrounding array) so per-item results stay streamable — this covers list reads (`selection ls`, `selection focus`, `node ls`, `node grep`, `asset ls`, `folder ls`, `models`, `voices`, `fonts`), selection mutations that return the new state, and batch operations (`node rm`, `node patch`, `node cp`, `asset add`, `asset rm`, `asset mv`, `asset export`, `folder mv`, `folder rm`). `node tree` emits one nested JSON object per root, and `asset tree` emits one nested object per root entry. Exceptions: `open` for file / URL / no-target writes nothing; `fonts --names-only` writes plain family names; `mount` and `node insert` write nothing.
- **Unix-style names are canonical:** list/read → `ls`, delete/remove → `rm`, duplicate → `cp`, move/reparent → `mv`, search → `grep`. The longer English forms (`list`, `remove`, `duplicate`, `move`) are aliases of the Unix forms, not the other way around. `get` is a universal alias for `ls` on every command that has one. Applied wherever the semantics match; commands without a natural Unix equivalent (`tree`, `rename`, `patch`, `add`, `create`, `active`, `context`, `whoami`, `open`, `focus`, `set`) keep their descriptive names.
- **Stderr:** human-readable error messages.
- **Exit codes:** `0` on success, `1` on any error (missing file, app not running, invalid input, IPC error).
diff --git a/apps/cli/src/cli-channels.ts b/apps/cli/src/cli-channels.ts
index 3bb7fd12..335550e9 100644
--- a/apps/cli/src/cli-channels.ts
+++ b/apps/cli/src/cli-channels.ts
@@ -20,6 +20,7 @@ export const CLI_CHANNELS = {
CONTEXT: "cli:context",
ASSETS_ADD: "cli:assets:add",
ASSETS_LIST: "cli:assets:list",
+ ASSET_TREE: "cli:asset:tree",
ASSETS_DELETE: "cli:assets:delete",
ASSETS_MOVE: "cli:assets:move",
ASSETS_EXPORT: "cli:assets:export",
@@ -167,6 +168,12 @@ export type FolderInfo = { id: string; name: string; type: "folder" };
export type AssetTreeEntry = { id: string; name: string; type: string; children?: AssetTreeEntry[] };
+export type AssetRecord = { id: string } & Record<string, unknown>;
+
+export type AssetListResult =
+ | { status: "fulfilled"; asset: AssetRecord }
+ | { status: "rejected"; id: string; error: string };
+
export type AssetMoveResult =
| { status: "fulfilled"; id: string; folderId: string | null }
| { status: "rejected"; id: string; error: string };
@@ -213,6 +220,10 @@ export type CliRequestMap = {
response: any;
};
[CLI_CHANNELS.ASSETS_LIST]: {
+ request: { ids?: string[] };
+ response: AssetListResult[];
+ };
+ [CLI_CHANNELS.ASSET_TREE]: {
request: { folderId?: string; depth?: number };
response: AssetTreeEntry[];
};
diff --git a/apps/cli/src/cli-client.ts b/apps/cli/src/cli-client.ts
index c773c98c..1db8e01a 100644
--- a/apps/cli/src/cli-client.ts
+++ b/apps/cli/src/cli-client.ts
@@ -76,8 +76,9 @@ export const cliAPI = {
context: () => cliRequest(CLI_CHANNELS.CONTEXT, undefined),
addAssets: (paths: string[], folderId?: string) =>
cliRequest(CLI_CHANNELS.ASSETS_ADD, { paths, folderId }),
- listAssets: (folderId?: string, depth?: number) =>
- cliRequest(CLI_CHANNELS.ASSETS_LIST, { folderId, depth }),
+ listAssets: (ids?: string[]) => cliRequest(CLI_CHANNELS.ASSETS_LIST, { ids }),
+ assetTree: (folderId?: string, depth?: number) =>
+ cliRequest(CLI_CHANNELS.ASSET_TREE, { folderId, depth }),
deleteAssets: (ids: string[]) => cliRequest(CLI_CHANNELS.ASSETS_DELETE, { ids }),
moveAssets: (ids: string[], to?: string) => cliRequest(CLI_CHANNELS.ASSETS_MOVE, { ids, to }),
exportAssets: (ids: string[], output: string, isDir: boolean) =>
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index 2945609c..306aded8 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -146,9 +146,28 @@ async function addAssets(paths: string[], opts: AssetAddOptions): Promise<void>
}
}
-type AssetListOptions = { folder?: string; depth?: string };
+async function listAssets(ids: string[]): Promise<void> {
+ try {
+ // No ids → every asset in the library; with ids → those specific assets.
+ const results = await cliAPI.listAssets(ids.length ? ids : undefined);
+ let failed = false;
+ for (const result of results) {
+ if (result.status === "fulfilled") {
+ console.log(JSON.stringify(result.asset));
+ } else {
+ console.error(result.error);
+ failed = true;
+ }
+ }
+ if (failed) process.exit(1);
+ } catch (e) {
+ handleSocketError(e);
+ }
+}
+
+type AssetTreeOptions = { folder?: string; depth?: string };
-async function listAssets(opts: AssetListOptions): Promise<void> {
+async function assetTree(opts: AssetTreeOptions): Promise<void> {
let depth: number | undefined;
if (opts.depth !== undefined) {
const n = Number(opts.depth);
@@ -160,7 +179,7 @@ async function listAssets(opts: AssetListOptions): Promise<void> {
}
try {
- const results = await cliAPI.listAssets(opts.folder, depth);
+ const results = await cliAPI.assetTree(opts.folder, depth);
for (const result of results) console.log(JSON.stringify(result));
} catch (e) {
handleSocketError(e);
@@ -975,11 +994,17 @@ asset
asset
.command("ls")
- .aliases(["list", "get"])
- .description("List the asset library of the open project as its folder tree")
+ .alias("get")
+ .description("Print raw asset records — every persisted property except the file handles; with no ids, lists every asset")
+ .argument("[ids...]", "asset ids to list (optional)")
+ .action((ids: string[]) => listAssets(ids));
+
+asset
+ .command("tree")
+ .description("Print the asset library of the open project as its folder tree")
.option("--folder <id>", "folder whose contents to list (default: the library root)")
.option("--depth <n>", "max depth to descend (positive integer; default = full tree)")
- .action((opts: AssetListOptions) => listAssets(opts));
+ .action((opts: AssetTreeOptions) => assetTree(opts));
asset
.command("rm")
diff --git a/apps/web/src/context/electron/assets.ts b/apps/web/src/context/electron/assets.ts
index 4d010a27..506f35ec 100644
--- a/apps/web/src/context/electron/assets.ts
+++ b/apps/web/src/context/electron/assets.ts
@@ -20,7 +20,7 @@ import {
import type { Engine } from "@/components/engine";
import type { Asset } from "@/components/engine/db";
-import type { AssetAnalyzeRequest, AssetAnalyzeResult, AssetExportResult, AssetMoveResult, AssetProbeRequest, AssetsExportRequest, AssetTranscribeResult, AssetTreeEntry, AssetVisualizeRequest, AssetVisualizeResult } from "@diffusionstudio/cli/channels";
+import type { AssetAnalyzeRequest, AssetAnalyzeResult, AssetExportResult, AssetListResult, AssetMoveResult, AssetProbeRequest, AssetRecord, AssetsExportRequest, AssetTranscribeResult, AssetTreeEntry, AssetVisualizeRequest, AssetVisualizeResult } from "@diffusionstudio/cli/channels";
import type { Accessor } from "solid-js";
export function handleAssetsAdd(engine: Accessor<Engine>) {
@@ -42,7 +42,40 @@ export function handleAssetsAdd(engine: Accessor<Engine>) {
}
}
+/**
+ * The persisted asset record minus the props that can't cross the wire
+ */
+function toAssetRecord(asset: Asset): AssetRecord {
+ const record: Record<string, unknown> = { ...asset };
+ delete record.handle;
+ delete record.directoryHandle;
+ delete record.hash;
+ delete record.transcript;
+ return record as AssetRecord;
+}
+
export function handleAssetsList(engine: Accessor<Engine>) {
+ return async ({ ids }: { ids?: string[] }): Promise<AssetListResult[]> => {
+ const { world } = engine();
+
+ // No ids → every asset in the library
+ if (ids === undefined || ids.length === 0) {
+ return Array.from(world.assets.values()).map((asset) => ({
+ status: "fulfilled",
+ asset: toAssetRecord(asset),
+ }));
+ }
+
+ return ids.map((id) => {
+ const asset = world.assets.get(id);
+ return asset
+ ? { status: "fulfilled", asset: toAssetRecord(asset) }
+ : { status: "rejected", id, error: `No such asset: ${id}` };
+ });
+ };
+}
+
+export function handleAssetTree(engine: Accessor<Engine>) {
return async ({ folderId, depth }: { folderId?: string; depth?: number }): Promise<AssetTreeEntry[]> => {
const { world } = engine();
if (folderId !== undefined) {
diff --git a/apps/web/src/context/electron/electron.tsx b/apps/web/src/context/electron/electron.tsx
index db7a072e..d4ab79fc 100644
--- a/apps/web/src/context/electron/electron.tsx
+++ b/apps/web/src/context/electron/electron.tsx
@@ -12,7 +12,7 @@ import { CLI_CHANNELS } from '@diffusionstudio/cli/channels';
import { MAIN_CHANNELS } from '@desktop/main-channels';
import { assert } from "@/utils/common";
import { handleContextGet } from "./context";
-import { handleAssetsAdd, handleAssetsList, handleAssetsDelete, handleAssetsMove, handleAssetsExport, handleAssetProbe, handleAssetFrame, handleAssetTranscribe, handleAssetVisualize, handleAssetAnalyze } from "./assets";
+import { handleAssetsAdd, handleAssetsList, handleAssetTree, handleAssetsDelete, handleAssetsMove, handleAssetsExport, handleAssetProbe, handleAssetFrame, handleAssetTranscribe, handleAssetVisualize, handleAssetAnalyze } from "./assets";
import { handleFoldersList, handleFolderCreate, handleFolderRename, handleFoldersMove, handleFoldersDelete } from "./folders";
import { handleSelectionFocus, handleSelectionList, handleSelectionSet } from "./selection";
import { handleNodeList, handleNodeTree, handleNodeGrep, handleNodeScreenshot, handleNodeDelete, handleNodePatch, handleNodeDuplicate, handleNodeRender } from "./node";
@@ -57,6 +57,7 @@ export function ElectronProvider(props: ElectronProviderProps) {
const unsubContext = cliBridge.handle(CLI_CHANNELS.CONTEXT, handleContextGet(engineRef));
const unsubAssetsAdd = cliBridge.handle(CLI_CHANNELS.ASSETS_ADD, handleAssetsAdd(engineRef));
const unsubAssetsList = cliBridge.handle(CLI_CHANNELS.ASSETS_LIST, handleAssetsList(engineRef));
+ const unsubAssetTree = cliBridge.handle(CLI_CHANNELS.ASSET_TREE, handleAssetTree(engineRef));
const unsubAssetsDelete = cliBridge.handle(CLI_CHANNELS.ASSETS_DELETE, handleAssetsDelete(engineRef));
const unsubAssetsMove = cliBridge.handle(CLI_CHANNELS.ASSETS_MOVE, handleAssetsMove(engineRef));
const unsubAssetsExport = cliBridge.handle(CLI_CHANNELS.ASSETS_EXPORT, handleAssetsExport(engineRef));
@@ -96,6 +97,7 @@ export function ElectronProvider(props: ElectronProviderProps) {
unsubContext();
unsubAssetsAdd();
unsubAssetsList();
+ unsubAssetTree();
unsubAssetsDelete();
unsubAssetsMove();
unsubAssetsExport();
diff --git a/docs/assets.md b/docs/assets.md
index 09129459..da28e488 100644
--- a/docs/assets.md
+++ b/docs/assets.md
@@ -8,7 +8,8 @@ The asset library holds a project's media. Beyond storage, the CLI ships an insp
```sh
dapi asset add <paths...> [--folder <id>] # import files
-dapi asset ls [--folder <id>] [--depth N] # the library as a folder tree
+dapi asset ls [ids...] # raw asset records (all assets if no ids)
+dapi asset tree [--folder <id>] [--depth N] # the library as a folder tree
dapi asset mv <ids...> [--to <folderId>] # move assets between folders
dapi asset rm <ids...> # delete assets
dapi asset export <ids...> [-o <path>] # write original file bytes back to disk (no re-encode)
@@ -74,7 +75,7 @@ Puts a multimodal model in front of an image, video, or audio asset. Without a p
```sh
dapi open -b ./shoot # project from footage
-dapi asset ls --depth 1 # what's here?
+dapi asset tree --depth 1 # what's here?
dapi asset probe gbHJ # what format is it?
dapi asset visualize gbHJ # what does it look like over time?
dapi asset transcribe gbHJ # what is said, and when?
diff --git a/docs/composition.md b/docs/composition.md
index fedb7e6f..26b7f09b 100644
--- a/docs/composition.md
+++ b/docs/composition.md
@@ -78,7 +78,7 @@ These same props are what `dapi node patch` assigns on existing nodes.
- an **absolute path** like `"/Movies/clip.mp4"`
- a **remote URL**, registered as a remote asset
-- an **asset id**: an imported library asset (see `dapi asset ls`)
+- an **asset id**: an imported library asset (see `dapi asset tree`)
- an **`AssetRef`**: the value returned by a `generate.*` declaration
## Timing
diff --git a/docs/getting-started.md b/docs/getting-started.md
index ba98a9ba..f3025e6e 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -40,7 +40,7 @@ You can also manage projects directly: `dapi project create`, `dapi project ls`,
```sh
dapi context # the open project: scenes, active scene, playhead, fonts
-dapi asset ls # the media library as a folder tree
+dapi asset tree # the media library as a folder tree
```
`dapi context` (alias `ctx`) is the right first call in any session; it tells you what is on the canvas before you change it.