Rewrite a package directory's editor files, datumhue.d.lua (LuaLS annotations), .luarc.json (LuaLS settings) and .stylua.toml (formatter settings), for this version of DatumHue.
Publish a package directory's lockfile contents to a registry, after verifying the committed package.lock.kdl still resolves (run pkg update first if a dependency was yanked or removed).
Report a local package's registry dependencies that have a newer published version than its constraints currently resolve to, and flag any whose pinned version has since been yanked.
datumhue pkg pack
command
datumhue pkg pack [OPTIONS] [SOURCE]
Bundle a package directory into a .dhpkg archive. The source directory must contain a package.kdl manifest at its root. Output defaults to <scope>-<name>-<version>.dhpkg next to the source; override with --out. Source defaults to the current directory.
Argument
Default
Description
[SOURCE]
.
Package directory to archive. Must contain package.kdl. Defaults to the current directory
Option
Default
Description
--out<PATH>, -o
none
Destination .dhpkg path. If omitted, the archive is written next to source as <scope>-<name>-<version>.dhpkg
datumhue pkg info
command
datumhue pkg info [TARGET]
Print a one-line summary of a package: name, version, kind, file count, and content hash. Accepts a .dhpkg archive or a source directory.
Argument
Default
Description
[TARGET]
.
Path to a .dhpkg file or a package source directory. Defaults to the current directory
datumhue pkg ls
command
datumhue pkg ls [OPTIONS] [TARGET]
List the files inside a package — either a .dhpkg archive or a source directory. Paths are package-relative, sorted, one per line. Add --long to include per-file size and content hash columns.
Argument
Default
Description
[TARGET]
.
Path to a .dhpkg file or a package source directory. Defaults to the current directory
Option
Default
Description
--long
off
Emit size + content hash columns alongside each path
datumhue pkg cat
command
datumhue pkg cat <TARGET> <REL>
Print the raw bytes of a single file inside a package to stdout. Binary-safe — no encoding or framing. Errors if the requested path isn't in the bundle.
Argument
Default
Description
<TARGET>
required
Path to a .dhpkg file or a package source directory
<REL>
required
Package-relative path to read
datumhue pkg hash
command
datumhue pkg hash [TARGET]
Print just the content hash of a package to stdout — nothing else, single line, shell-pipeable. Accepts a .dhpkg file or a source directory.
Argument
Default
Description
[TARGET]
.
Path to a .dhpkg file or a package source directory. Defaults to the current directory
datumhue pkg unpack
command
datumhue pkg unpack [OPTIONS] <ARCHIVE>
Extract a .dhpkg archive back to a directory. Errors if the output directory already exists and is non-empty unless --force is supplied.
Argument
Default
Description
<ARCHIVE>
required
.dhpkg archive to extract
Option
Default
Description
--out<DIR>, -o
none
Output directory. Defaults to the archive's stem in the current working directory
--force
off
Allow overwriting existing files in the output dir
datumhue pkg new
command
datumhue pkg new [OPTIONS] <DIR>
Scaffold a new package directory with package.kdl, init.lua, empty lib/ and assets/ directories, and a .dhignore with common editor-artifact patterns. kind defaults to "app". Errors if <dir> already exists and is non-empty.
Argument
Default
Description
<DIR>
required
Directory to create and scaffold into
Option
Default
Description
--name<NAME>
none
Scoped package identity @scope/name, e.g. @your-scope/my-package. Both segments are lowercase letters, digits, _, or -, starting with a letter or digit; _ is folded to -
--kind<KIND>
app
Manifest kind. The refinements (theme, book, dataset, ...) scaffold as asset_pack packages with the matching content_type.
One of:
app: Runnable app: init.lua, launchable
library: requireable library: lib/ tree, no init.lua
asset_pack: Bytes-only bundle with no code
theme: Asset pack carrying a theme
book: Asset pack carrying a book; scaffolds starter pages
dataset: Asset pack carrying a dataset
template: Asset pack carrying a template
font_pack: Asset pack carrying fonts
shader_pack: Asset pack carrying shaders
media: Asset pack carrying media files
--service
off
Scaffold a service app: sets service #true in the manifest and uses an init.lua template oriented around messaging instead of UI. Only valid with --kind app
datumhue pkg refresh
command
datumhue pkg refresh [SOURCE]
Rewrite a package directory's editor files, datumhue.d.lua (LuaLS annotations), .luarc.json (LuaLS settings) and .stylua.toml (formatter settings), for this version of DatumHue. Run it after an upgrade to get annotations for new APIs. Leaves package.kdl, init.lua, lib/ and assets/ alone.
Argument
Default
Description
[SOURCE]
.
Package directory to refresh. Must contain package.kdl. Defaults to the current directory
datumhue pkg check
command
datumhue pkg check [SOURCE]
Validate a package directory without packing it. Parses the manifest, checks the layout, rejects reserved paths, applies .dhignore, applies the publish license policy (a free package must declare a license the registry may redistribute it under), and resolves requires against sibling packages. Exit 0 on success with an OK summary line; exit 1 on failure with per-problem diagnostics.
Argument
Default
Description
[SOURCE]
.
Package directory to validate. Must contain package.kdl. Defaults to the current directory
datumhue pkg test
command
datumhue pkg test [OPTIONS] [DIR] [FILTER]... [-- <ARGS>...]
Run the package's test suite from its tests/ directory. Test modules (tests/*_test.lua) register suites with describe/it; results stream as TAP on stdout. Service packages run without a window; windowed packages open one. Exit 0 when every test passes, 1 on test failures, 2 on usage, assembly, or pre-flight errors.
Argument
Default
Description
[DIR]
.
Package directory containing a tests/ suite. Defaults to the current directory
[FILTER]...
none
Run only tests whose full name (suite > name) contains any FILTER substring. A filter that matches nothing fails the run
[ARGS]...
none
Everything after -- reaches the suite via datumhue.args.argv
Option
Default
Description
--list
off
List test names without running anything
--skip<PAT>
none
Skip tests whose full name contains PAT (repeatable). A pattern that matches nothing fails the run
--seed<SEED>
none
Seed mixed into every test's RNG stream. Each run prints the seed it used; pass it back to reproduce the run
--timeout<SECS>
none
Whole-run watchdog in seconds. Overrides the suite's tests/test.kdltimeout-seconds (default 300)
--report<PATH>
none
Also write an HTML report of the run to PATH
--open
off
Write the HTML report (to --report PATH or a temporary file) and open it in the system browser after the run
--dap
off
Serve the assembled suite on a DAP listener instead of running it: connect an editor, set breakpoints on the real source paths (tests/ included), and send launch
--dap-listen<HOST:PORT>
127.0.0.1:4711
Address for the --dap listener
--profile<PATH>
none
Record a sampling profile of the suite's script execution and write it to PATH after the run, in speedscope JSON format with one profile per app
--profile-summary<PATH>
none
Also write a profiling summary as JSON to PATH: per-function call counts with self and total times, plus per-app frame-budget statistics
--dir<NAME:PATH>
none
Grant a read-only directory capability (NAME:PATH)
--dir-rw<NAME:PATH>
none
Grant a read-write directory capability (NAME:PATH)
Run the package's test suite with line and branch coverage of the package's Lua code. After the run, prints a per-file covered/total table; modules the suite never loaded count as uncovered. Exit 0 on a passing run (within any --fail-under / --fail-under-branch bound), 1 on test failures or a missed bound, 2 on usage, assembly, or pre-flight errors.
Argument
Default
Description
[DIR]
.
Package directory containing a tests/ suite. Defaults to the current directory
[FILTER]...
none
Run only tests whose full name (suite > name) contains any FILTER substring. A filter that matches nothing fails the run
[ARGS]...
none
Everything after -- reaches the suite via datumhue.args.argv
Option
Default
Description
--skip<PAT>
none
Skip tests whose full name contains PAT (repeatable). A pattern that matches nothing fails the run
--seed<SEED>
none
Seed mixed into every test's RNG stream. Each run prints the seed it used; pass it back to reproduce the run
--timeout<SECS>
none
Whole-run watchdog in seconds. Overrides the suite's tests/test.kdltimeout-seconds (default 300)
--lcov<PATH>
none
Also write an LCOV tracefile to PATH
--fail-under<PCT>
none
Exit non-zero when total line coverage is below PCT
--fail-under-branch<PCT>
none
Exit non-zero when total branch coverage is below PCT. Branches are condition-level: each conditional gets two outcomes, and an a and b condition counts as two branches
--report<PATH>
none
Also write an HTML report of the run — test results plus per-file line and branch coverage over the package's source — to PATH
--open
off
Write the HTML report (to --report PATH or a temporary file) and open it in the system browser after the run
--dir<NAME:PATH>
none
Grant a read-only directory capability (NAME:PATH)
--dir-rw<NAME:PATH>
none
Grant a read-write directory capability (NAME:PATH)
--file<NAME:PATH>
none
Grant a read-only file capability (NAME:PATH)
--file-rw<NAME:PATH>
none
Grant a read-write file capability (NAME:PATH)
datumhue pkg update
command
datumhue pkg update [OPTIONS] [SOURCE]
Resolve a package's dependencies against the registry and write package.lock.kdl. Registry dependencies are pinned to the published content they currently resolve to; yanked versions are skipped. Workspace dependencies are pinned when the workspace is published. When you are signed in, a paid dependency you bought lands in the project's deps/ directory, and the lock records it as vendored. Run this to move onto newer or un-yanked dependency versions; pkg push then publishes against the lock without re-resolving.
Exit codes: 0 = lockfile already up to date, 1 = local error, 3 = the lockfile changed (or would change, with --dry-run), 5 = the deployment could not be reached, 9 = a dependency could not be resolved. Delivering a paid dependency needs the sign-in: 6 = not signed in, 7 = sign-in expired and could not be renewed, 8 = the deployment's sign-in configuration has changed since last login.
Argument
Default
Description
[SOURCE]
.
Package directory to update. Defaults to the current directory. With --workspace, a directory inside the workspace
Option
Default
Description
--namespace<NAME>
none
Registry namespace the package is published in; the lock records each dependency's namespace against it. Defaults to the namespace workspace.kdl gives the package, else its @scope. A dependency without namespace= resolves in its own @scope. With --workspace, the default for members that don't set their own.
Update every member of the enclosing workspace.kdl in one pass
--dry-run
off
Resolve and print what would change without writing the lockfile
datumhue pkg license
command
datumhue pkg license [ID]
Print the package licenses DatumHue accepts. Without an id, lists every accepted license with a one-line reading. With an id, prints that license's full text (or, for ids with no public text, what the id means and where its terms come from).
Argument
Default
Description
[ID]
none
License id to print, e.g. "0BSD", "MIT-0", "CC0-1.0", "LicenseRef-DatumHue-Freeware", "LicenseRef-Proprietary"
datumhue pkg docs
command
datumhue pkg docs [OPTIONS] [SOURCE]
Generate documentation for a package directory — its modules and exports, the package README as a guide, and its dependencies. --format selects Markdown, JSON, or a self-contained searchable HTML page (the default); --open builds the HTML page and opens it in your browser. Prints to stdout by default; use --out to write a file. Resolves dependencies the same way pkg check does.
Argument
Default
Description
[SOURCE]
.
Package directory to document. Defaults to the current directory
Option
Default
Description
--format<FORMAT>
html
Output format.
One of:
html: Self-contained HTML page with a sidebar, deep links and search
markdown: Free-form Markdown
json: Structured JSON
--out<PATH>, -o
none
Write the output to this path instead of stdout
--open
off
Build the searchable HTML page and open it in the system browser. Writes to --out when given, otherwise a temp file
--deps<DEPS>
compact
How much of each dependency to include: a card (compact), the dependency's full surface inlined (full), or nothing (none).
One of:
none: Omit the section entirely
compact: A compact summary — a card per dependency, or a stub per core type — that the referencing signatures link to
full: Inline the full content in-page
--core<CORE>
compact
How much of each referenced DatumHue core type to include: a stub (compact), the full type inlined (full), or nothing (none). Core types stay recognized and styled either way.
One of:
none: Omit the section entirely
compact: A compact summary — a card per dependency, or a stub per core type — that the referencing signatures link to
full: Inline the full content in-page
--namespace<NAME>
none
Document a published package from this namespace's catalog instead of a local directory; <source> is then the package name. Connects to the deployment
datumhue pkg uuid
command
datumhue pkg uuid
Print a fresh random UUID to stdout — one line, nothing else. datumhue.storage.open_shared names a shared store by such a UUID.
datumhue pkg push
command
datumhue pkg push [OPTIONS] [SOURCE]
Publish a package directory's lockfile contents to a registry, after verifying the committed package.lock.kdl still resolves (run pkg update first if a dependency was yanked or removed). With --workspace, publishes every member of the enclosing workspace.kdl in dependency order: a member's workspace dependency is published first, so the dependent pins its real published content. Members already published at their version are skipped, so a re-run resumes after a partial failure. Sign in first with datumhue login.
Exit codes: 0 = published, 1 = local error, 2 = the sign-in was rejected, 3 = signed-in user is not allowed to publish, 4 = manifest invalid, 5 = the deployment could not be reached, a registry error, or the sign-in could not be checked, 6 = not signed in, 7 = sign-in expired and could not be renewed, 8 = the deployment's sign-in configuration has changed since last login, 9 = the lockfile is stale or a dependency could not be resolved, 10 = the signed-in user does not own the package's scope, 11 = the version is already published with different content.
Argument
Default
Description
[SOURCE]
.
Package directory to publish. Must contain package.kdl. With --workspace, a directory inside the workspace. Defaults to the current directory
Option
Default
Description
--namespace<NAME>
none
Target registry namespace. Defaults to the namespace workspace.kdl gives the package, else its @scope. With --workspace, the default for members that don't set their own.
Publish every member of the enclosing workspace.kdl, in dependency order
--dry-run
off
Verify and build locally (with --workspace, stage and order the whole workspace), then exit without sending anything to the registry
datumhue pkg namespaces
command
datumhue pkg namespaces
List the package namespaces the deployment serves.
datumhue pkg search
command
datumhue pkg search [OPTIONS] [QUERY]
Search the deployment's package catalogs: every namespace it serves, or only --namespace. Each row names the namespace the package is published in. With no query, lists every package; a query matches names and descriptions. Narrow with --tags and --kind. A namespace that can't be read is named on stderr and the rest still list. Connects to the deployment.
Argument
Default
Description
[QUERY]
none
Case-insensitive text matched against package name and description. Omit to list every package
Show a catalog package's metadata — version, kind, description, tags, capabilities, and dependencies — without downloading it. Connects to the deployment.
Argument
Default
Description
<NAME>
required
Scoped package name @scope/name
Option
Default
Description
--namespace<NAME>
none
Registry namespace to address. Defaults to the package's @scope.
Yank a published version: it drops out of version-range resolution and catalog listings, so new installs skip it. The bytes are never deleted — an exact =X.Y.Z request and already-pinned consumers keep resolving it. Use --undo to re-list. Requires ownership of the package's scope; sign in first with datumhue login.
Exit codes: 0 = done, 1 = local error, 2 = the sign-in was rejected, 3 = signed-in user is not allowed to yank, 5 = the deployment could not be reached, a registry error, or the sign-in could not be checked, 6 = not signed in, 7 = sign-in expired and could not be renewed, 8 = the deployment's sign-in configuration has changed since last login, 10 = the signed-in user does not own the package's scope, 11 = the version is not published.
Argument
Default
Description
<NAME>
required
Scoped package name @scope/name
<VERSION>
required
Exact version to yank
Option
Default
Description
--namespace<NAME>
none
Registry namespace to address. Defaults to the package's @scope.
Reason recorded with the yank, surfaced when resolution skips the version and in pkg show
--undo
off
Reverse a previous yank — re-list the version for resolution
datumhue pkg price
command
datumhue pkg price [OPTIONS] <NAME> [AMOUNT]
Show or set a paid package's listing price. With an amount, lists (or relists) the package for sale at that price; without one, shows the current listing. Requires ownership of the package's scope; sign in first with datumhue login.
Exit codes: 0 = done, 1 = local error, 2 = the sign-in was rejected, 3 = signed-in user is not allowed to set prices, 4 = the package is free or the amount or currency is invalid, 5 = registry error or the platform could not be reached, 6 = not signed in, 7 = sign-in expired and could not be renewed, 8 = the deployment's sign-in configuration has changed since last login, 11 = the package is not published.
Argument
Default
Description
<NAME>
required
Scoped package name @scope/name
[AMOUNT]
none
Amount in the currency's minor unit (e.g. cents). Omit to show the current listing
Option
Default
Description
--currency<CURRENCY>
usd
ISO 4217 currency code, lowercase
--namespace<NAME>
none
Registry namespace to address. Defaults to the package's @scope.
List the published packages, in every namespace the deployment serves, that depend on a package. Each row names the namespace the dependent is published in. The rows read are printed even when a namespace can't be read; that namespace is named on stderr. Connects to the deployment.
Exit codes: 0 = every namespace was read, 1 = a namespace could not be read, or another error.
Argument
Default
Description
<NAME>
required
Scoped package name @scope/name to find dependents of
Option
Default
Description
--namespace<NAME>
none
Registry namespace to address. Defaults to the package's @scope.
Report a local package's registry dependencies that have a newer published version than its constraints currently resolve to, and flag any whose pinned version has since been yanked. Reads package.kdl and connects to the deployment.
Argument
Default
Description
[SOURCE]
.
Package directory to check. Defaults to the current directory
Option
Default
Description
--namespace<NAME>
none
Registry namespace the package is published in; the lock records each dependency's namespace against it. Defaults to the namespace workspace.kdl gives the package, else its @scope. A dependency without namespace= resolves in its own @scope.