dsa is a standalone Node 24+ CLI with bundled validation, templates, and static rendering. It prints JSON by default and writes actionable errors to stderr. It stores no configuration, login session, or credentials.
npm install -g https://github.com/bestagentkits/design-studio-ai/releases/download/v0.4.3/bestagentkits-design-studio-ai-0.4.3.tgz
dsa --help
dsa projects export --help
dsa media generate --helpCommand reference
All commands below begin with dsa. Options without “required” are optional. Use command --help for the installed version. Document/operation input accepts --file - for stdin; prompt input accepts --prompt-file -.
| Command | Options | Behavior |
|---|---|---|
community schema | No options | Discover every Community command and canonical request shape. |
community taxonomy | No options | Discover Community categories, formats and limits |
community search | --q TEXT --kind KIND --tags TAGS --format FORMAT --period PERIOD --creator HANDLE --collection ID --sort SORT --cursor CURSOR --limit N | Search live community designs with category, tags, formats, sort and cursor filters |
community get ID | No options | Read a live design and its download files |
community creator HANDLE | No options | Read a public creator profile |
community collections | No options | List curated Community collections |
community collection ID | No options | Read a curated Community collection |
community preview ID VERSION | --out FILE | Get sandboxed HTML preview of a retained live version |
community download ID VERSION FILEID | --out FILE | Download real ready file bytes; first eligible download contributes to creator impact |
community preflight | --file request.json | Review the public projection, disclosures, formats and digest before publishing |
community generate-metadata | --file request.json | Draft a listing title, description and tags using an owned saved project revision and configured text provider. Sends bounded visible text/structure plus entered fields/instructions, incurs provider usage, and never saves or publishes. Defaults to the first configured text connection. Review the suggestion and run preflight with the approved fields before publication. |
community publish | --file request.json | Explicitly confirm CC-BY-4.0 and public disclosure to publish the reviewed revision; reuse exact operation ID and payload on retry |
community release ID | --file request.json | Publish a new immutable release at the reviewed project and listing revisions |
community unlist ID | --file request.json | Revoke public access to all listing versions at the observed listing revision |
community job OPERATIONID | No options | Read your durable Community operation status and result |
community job-preview OPERATIONID | --out FILE | Read your private staged publication preview |
community job-file OPERATIONID FILEID | --out FILE | Download your private staged file |
community remix ID | --file request.json | Create an independent private project with owned assets and attribution from a pinned public version |
community import | --file design.zip --operation-id ID | Import a portable ZIP into an independent private project; operationId makes exact retries safe |
community my-listings | No options | List your publications including private management states |
community bookmarks | No options | List your private saved Community designs |
community impact | No options | Read server-confirmed creator impact and milestone badges |
community profile | No options | Read your opt-in Community profile and revision |
community set-profile | --file request.json | Create or update your public profile at its observed revision |
community generate-profile | --file request.json | Use your configured text provider to suggest a public display name, handle and bio. Incurs provider usage; sends only supplied fields/instructions, defaults to your first configured text connection, and never saves or publishes. Review before set-profile; handle availability is checked again when saving. |
community save ID | No options | Idempotently save a live design to your private bookmarks |
community unsave ID | No options | Idempotently remove a private bookmark |
community report ID | --file request.json | Report a pinned design version with a reason and exact-retry operation ID |
community reports | No options | Operator session/API key only: list private reports |
community moderation-collections | No options | Operator only: list collections including unavailable reviewed items |
community report-detail ID | No options | Operator only: inspect a pinned report and content availability |
community report-preview ID | --out FILE | Operator only: preview retained reported content |
community report-file ID FILEID | --out FILE | Operator only: download retained evidence bound to the report |
community resolve-report ID | --file request.json | Operator only: hide, restore or dismiss with observed report/listing revisions and a reason |
community create-collection | --file request.json | Operator only: curate explicitly reviewed listing versions |
community update-collection ID | --file request.json | Operator only: update ordered curation at the observed collection revision |
scene schema | No options | Discover bounded mesh, rig, pose, animation and UV commands. |
scene inspect PROJECT | --page PAGE --time SECONDS | Inspect saved 3D topology and sampled pose. |
scene command PROJECT | --page PAGE --revision N --file command.json [--apply] | Preview by default; --apply saves against the observed revision. |
observability summary | --scope owner|all --days N --project-id ID --actor-id ID --channel NAME --kind NAME --status NAME --action ACTION | Read activity/usage/coverage. All-account scope requires configured operator; actor filter only in all scope. |
observability events | Summary filters plus --limit N --cursor CURSOR | Read safe paginated activity events. |
observability trace ID | --scope owner|all --days N | Read correlated request steps within 1–30 days; default7. |
health · config | No required options | Read public health/configuration; never persist credentials. |
schema | --operations | Print document JSON Schema or targeted-operation schema. |
motion PROJECT_ID | --character ID --node ID --time SECONDS | Inspect reusable rigs and sample an instance pose without a provider call. |
catalog | No options | List bundled themes, templates, and blocks. |
themes list · get ID | No required options | Inspect design tokens and palettes. |
templates list · get ID | list: --kind KIND | Inspect supported starters. |
templates instantiate ID | --name NAME --theme ID --output FILE | Create a local document with fresh IDs; no server write. |
blocks list · get ID | get: --offset PIXELS | Inspect reusable node groups. |
design-systems schema · list | No required options | Discover the shared definition schema or your saved libraries. |
design-systems get ID | --system-version N | Read the latest or an immutable saved version. |
design-systems versions ID | No required options | List saved library versions. |
design-systems create | --file FILE required | Create a library from a validated definition; accepts stdin with --file -. |
design-systems update ID | --system-version N --file FILE required | Append a version using the version of the definition actually read; conflicts require reconciliation. |
design-systems apply ID PROJECT_ID | --revision N required; --system-version N | Apply saved tokens/system to an owned project and pin the selected library version. |
design-systems insert ID PROJECT_ID | --revision N --page PAGE_ID --item ITEM_ID required; --system-version N | Insert a saved component or composition into a project. |
design-systems remove ID | No required options | Delete the library and history; existing project designs remain intact. |
fonts | --query TEXT | Search Google font families/categories; inspect source for live/cache/fallback provenance. |
providers models ID | --query TEXT | Search the saved connection model catalog; custom endpoints retain manual IDs and labeled suggestions. |
projects list | --query TEXT --kind KIND --sort updated|created|name | Search persisted owned projects. |
projects check ID | No required options | Inspect saved design bounds, text fit, estimated contrast, media, and export limitations; never an accessibility certification. |
projects inspect ID | --output FILE required; --mode page|overview --page INDEX or --page-id ID --revision N --time SECONDS --offset N --limit N --columns N --tile-size PX --max-dimension PX | Write one saved-page PNG or project contact sheet, plus JSON metadata without base64. Page selectors require page mode; default overview returns six pages. Follow nextOffset. |
projects overview | --output-dir DIR required; --offset N --limit N --time SECONDS --tile-size PX | Write owner-workspace first-page covers and JSON metadata. Default six projects in ID order; follow nextOffset. Empty results write no files. |
projects get ID | No required options | Read document and saved revision. |
projects create | --name NAME required; --description TEXT --kind KIND --template ID --theme ID --file FILE | Create a persisted project. Choose --file or --template. |
projects rename ID NAME | --revision N required | Rename with an explicit observed revision. |
projects clone ID | --name NAME | Create an independent project, copying owned media bytes. |
projects delete ID | No required options | Delete project, assets, and publications. |
brief get ID | No required options | Read the persisted interview, answers, scope, and independent brief revision. |
brief put ID | --revision N --file FILE required | Save request/interview/answers/scope; revision 0 creates. Input file excludes expectedRevision. Invalidates approval. |
brief interview ID | --revision N --provider ID required; --model ID | Generate and persist contextual questions/scope using configured BYOK; charges may apply. |
brief approve ID | --revision N required | Record explicit human approval of the current answered scope. Does not generate or publish. |
projects paint ID | --file FILE required | Render a stroke/fill with the paintingCommand revision, generation and operationId guards. |
projects document get ID | --output FILE | Read the canonical document. |
projects document put ID | --file FILE --revision N required; --brief-revision N for proposals | Save a complete validated document with atomic concurrency protection. |
projects document patch ID | --file FILE --revision N required | Apply a targeted operation array and save atomically. |
projects document merge ID | --file FILE required | Merge JSON {base, document, baseRevision} against the exact document/revision originally read; overlapping edits require reconciliation. Accepts - for stdin. |
projects document changes ID | --since N (default 0) | Read the current saved revision and project when changed, or unchanged: true at the observed revision. N must be nonnegative. |
projects import | --file FILE required; --name NAME | Create a new project from canonical JSON. |
projects thumbnail ID | --output FILE required; --revision N | Download a persisted private PNG cover. A busy request returns rendering status and retryAfterSeconds; retry before claiming a file exists. |
projects export ID | --format FORMAT required; --output FILE / --out FILE --page INDEX --revision N --start SECONDS --end SECONDS --fps FPS --review-samples COUNT --node ID | Download real server bytes. scene-angles uses end/review-samples (2–25); editable-scene uses node for canonical JSON. REST/MCP fields are reviewSamples and nodeId. Binary formats require a file. |
render | --file FILE --format json|html|svg required; --output FILE --page INDEX --time SECONDS | Render offline; preserves references without fetching private media. |
assets list PROJECT_ID | No required options | List stored assets. |
assets upload PROJECT_ID | --file FILE required; --mime TYPE | Upload media; placing it is a separate edit. |
assets download ASSET_ID | --output FILE required | Download authenticated bytes to a file. |
generate PROJECT_ID | --provider ID --revision N required; --prompt TEXT or --prompt-file FILE; --model ID --output FILE --mode document|motion | Generate a proposal without saving; BYOK charges may apply. |
providers list · remove ID | No required options | Read masked configurations or remove a connection. |
providers set ID | --key-env VARIABLE or --key-stdin or --keep-key; --base-url URL --model ID; custom: --name NAME --protocol FORMAT --auth-method METHOD --auth-header HEADER | Otherwise reads PROVIDER_API_KEY, e.g. OPENAI_API_KEY. |
tokens list · revoke ID | No required options | List metadata or revoke access. |
tokens create | --name NAME required | Returns the newly created secret once. |
publish · unpublish PROJECT_ID | No required options | Create a public snapshot or remove all project snapshots. |
preview · unpreview PROJECT_ID | No required options | Create a public preview link or remove all project snapshots. |
share · unshare PROJECT_ID | No required options | Create a public share link or remove all project snapshots. |
media generate PROJECT_ID | --kind KIND --provider ID required; --prompt TEXT or --prompt-file FILE; --model ID --voice ID --source-asset ID --duration SECONDS --strength NUMBER | Generate/edit image, video, speech, music, or effects using compatible modes. |
media status PROJECT_ID JOB_ID | No required options | Poll queued fal media or Leonardo images. |
google-slides PROJECT_ID | --key-env VARIABLE or --key-stdin | Defaults to GOOGLE_ACCESS_TOKEN; creates a real supported presentation. |
api METHOD /api/path | --file FILE | Same-origin REST escape hatch; no JSON body for GET/HEAD. |
See the saved design
Visual inspection returns private rendered PNGs with project/page identity, saved revision, dimensions, sampled time, image index and pixel bounds. It does not publish, call an AI provider, or change the document or brief. Save and verify local browser changes first.
dsa projects inspect PROJECT_ID --revision OBSERVED_REVISION --output pages.png
dsa projects inspect PROJECT_ID --mode page --page 0 --revision OBSERVED_REVISION --output page.png
dsa projects overview --output-dir reviewProject inspection defaults to a six-page contact sheet; workspace overview returns first-page covers of six owned projects in ID order. Follow non-null nextOffset with --offset to cover the rest. Use page mode for text and detail, selecting either --page or --page-id. Add --time to sample motion. A workspace result carries individual project revisions, not an atomic workspace snapshot.
Open the returned PNG files with an image viewer before claiming visual review. CLI stdout contains metadata and images[].path/bytes, never raw base64. Workspace files use workspace-OFFSET-IMAGE_INDEX.png; repeating the same output replaces them. Failed API requests create no image files; empty results write none. A still image does not prove responsive behavior, playback, sound, or browser compatibility.
Discover current limits through command help and visualInspection/workspaceInspection schemas. Renderer asset and resource limits apply; failures are explicit. REST returns PNG base64; MCP and WebMCP return real image blocks. The agent review workflow explains coverage and evidence.
Files and exit codes
JSON is the default for metadata. Document/template/export content sent to stdout is raw. --output writes the file and returns metadata; binary exports require a filename. Exit codes: 0 success, 1 input/API/conflict, 2 authentication/authorization, 3 network/invalid response, 4 local file/runtime error.
dsa providers set openai --key-env OPENAI_API_KEY
dsa media generate PROJECT_ID --kind image --provider openai \
--source-asset ASSET_ID --prompt-file edit.txt
dsa providers set fal --key-env FAL_API_KEY
dsa media generate PROJECT_ID --kind audio --provider fal \
--duration 30 --prompt-file music.txt
dsa media status PROJECT_ID JOB_IDSource type selects a compatible default model. --strength is for fal image/audio transformations, --voice for OpenAI speech. All fal modes and Leonardo images queue real jobs; poll to completion before claiming an asset exists. The package is distributed through GitHub Releases, not the npm registry.