@nonameno/dust-alt

A souped-up Dust experience for your terminal and your browser, in a single install — a personal fork of the Dust CLI and its web UI.

Unofficial project. Not affiliated with, nor endorsed by, Dust.

Installing this package gives you two commands:

| Command | What it is | | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | dust-alt | A fork of the official Dust CLI (terminal UI), with extra features. Named dust-alt so it never clashes with an official dust. | | dust-web | An original local web UI that brings the comfort of a graphical Dust interface together with everything the CLI can do. |

Install

⚠️ Install globally with -g. These are command-line tools, so they must be installed globally to put the dust-alt and dust-web commands on your PATH. The npm i @nonameno/dust-alt snippet npm shows at the top of this page (without -g) is auto-generated and will not make the commands available — use the line below instead.

npm install -g @nonameno/dust-alt

Requires Node.js >= 20.19 (tested on 26.x). Works on Linux, macOS and Windows.

Then run from anywhere:

dust-alt --version     # Dust CLI v0.4.5 · dust-alt v1.0
dust-web               # http://127.0.0.1:7321

Using nvm? Global installs are per-Node-version: if you switch Node versions, run npm install -g @nonameno/dust-alt once under the new one.

Linux servers / containers: the OS keychain needs libsecret. It's optional here — if it's absent, the tools fall back automatically to a credentials file (no crash). Install it only to use the real keychain — see Linux: libsecret below.

dust-alt — the enhanced CLI

A drop-in fork of the original Dust CLI that adds two features on top:

• Prompt history (Up / Down arrows). Recall and re-run your previous prompts with the arrow keys, just like a real shell.
• Full Anthropic-style skills. Complete skill support — including the scripts/ folder and supporting files, which the agent can reach by path. Drop your skills into ~/.dust-cli/skills/ and they become available automatically.

dust-alt            # start the interactive CLI
dust-alt --version

dust-web — the local web UI

An original creation that marries the best of both worlds: the mouse-and-window comfort of a web interface with the local power of the CLI. It runs entirely on your machine.

dust-web            # serves http://127.0.0.1:7321

What you get in the interface:

• Chat with Dust agents in a clean, fast web UI — mouse, scrolling, rich markdown, the whole graphical comfort.
• Local file system & tools. The agent can read and write files on your machine and run local tools through a built-in MCP file server — something the cloud web UI simply cannot do.
• Skills. The very same ~/.dust-cli/skills/ skills as the CLI, scripts folder included.
• Organize your conversations with pins and pinned folders: keep important threads grouped and one click away.
• Tasks & scheduler. Schedule recurring jobs — shell commands or AI-agent runs — daily, weekly, at a fixed interval, or one-off, with a run history for each task.
• Config panel, including how a message is handled while the agent is still busy (send now / stop & send / queue).
• Per-message timestamps and "completed in" durations.
• File uploads / attachments.

Environment variables

| Variable | Default | Description | | --------------- | ----------- | ---------------------------- | | DUST_WEB_PORT | 7321 | Port the server listens on. | | DUST_WEB_HOST | 127.0.0.1 | Host / interface to bind. |

Recommended: a dedicated dust-web agent

dust-web shines when you point it at a dedicated Dust agent tuned for this kind of local, tool-driven work. Create one in Dust with:

• Model: Claude Opus 4.8 with reasoning enabled (the best fit today).
• Tools (enable these four):
  • Web Search & Browse — search the internet and read web pages.
  • Image Generation — create and edit images.
  • Agent Memory — remember things across conversations.
  • Speech Generator — text-to-speech and multi-speaker dialogue.
• System prompt: paste the following so the agent integrates cleanly with dust-web (local file up/download, voice memos, attachments…):

You are a multi-purpose agent.

## At startup

Read your local skills with `fs_cli__list_agent_skills`.

## Local filesystem ↔ conversation

### Conversation → local FS (download)

```
GET http://localhost:7321/api/files/:fileId/download?inline=1
```

### Local FS → conversation (upload + attach)

```bash
curl -s -X POST \
  -F 'file=@/absolute/path/to/file' \
  -F 'conversationId=<CONVERSATION_ID>' \
  http://localhost:7321/api/files/upload
```

- `<CONVERSATION_ID>` from the `<dust_system>` block.
- Limit: 50 MB per file.
- Returns `{ fileId, fileName, fileSize, contentType, scopedToConversation: true }`.
- File becomes accessible via `files__list`, `files__cat`, `image_generation` (referenceImages).
- Does NOT pollute the next user message (uses storage-level scoping via useCaseMetadata).

### Avoid `fs_cli__read_file` for large binaries

Practical limit ~1 MB. Use upload+attach above for anything bigger or that needs to be processable by other tools.

Skills (~/.dust-cli/skills/)

Two ready-made Agent Skills ship with this package:

• create-skill — a meta-skill that teaches the agent how to scaffold a brand-new local skill on demand ("make me a skill that…"). Installing it first makes building further skills effortless.
• dust-tasks — drive the dust-web task scheduler in natural language.

Both dust-alt and dust-web discover skills under ~/.dust-cli/skills/. To install the bundled ones, copy them there and reload:

SKILLS="$(npm root -g)/@nonameno/dust-alt/skills"
mkdir -p ~/.dust-cli/skills
cp -r "$SKILLS/create-skill" "$SKILLS/dust-tasks" ~/.dust-cli/skills/
curl -X POST http://localhost:7321/api/skills/refresh   # or just restart dust-web

Windows: copy the two folders from %APPDATA%\npm\node_modules\@nonameno\dust-alt\skills into %USERPROFILE%\.dust-cli\skills\, then restart dust-web.

Configuration & data (~/.dust-cli/)

Both dust-alt and dust-web keep their state under ~/.dust-cli/ — the very same directory the official Dust CLI uses — so they share state with it (your authentication in particular). Notable files:

| Path | What it stores | | ------------------------------------- | --------------------------------------------------------- | | ~/.dust-cli/credentials.json | auth tokens (file fallback — see below) | | ~/.dust-cli/prompt-history.json | dust-alt prompt history (the ↑ / ↓ recall) | | ~/.dust-cli/dust-web-pinned.json | dust-web pinned conversations and their folder tree | | ~/.dust-cli/dust-web-tasks.json | dust-web scheduled tasks + run history | | ~/.dust-cli/dust-web-pretitle.json | dust-web conversation pretitles | | ~/.dust-cli/skills/ | your Agent Skills | | ~/.dust-cli/logs/YYYY-MM-DD.log | daily logs |

Authentication

By default, credentials are read from and written to your OS keychain via keytar, under the service name dust-cli — the exact same entry as the official CLI. So if you have already signed in once with the official dust CLI and hold a valid token, dust-alt and dust-web reuse it transparently: no second login.

If the keychain isn't available (no keytar, headless machine, no D-Bus / libsecret…) or there's no valid token there, they fall back to a plain JSON file at ~/.dust-cli/credentials.json (written with 600 permissions, atomic writes). Force the backend with the DUST_CREDENTIAL_STORE environment variable: auto (default), keychain (strict keychain), or file.

Linux: libsecret (optional)

keytar stores credentials in the OS keychain, and on Linux it needs libsecret. Unlike the official Dust CLI (which requires it), here it's optional: if libsecret is missing, dust-alt / dust-web don't crash — they automatically fall back to the ~/.dust-cli/credentials.json file store.

Install it only if you want to use the real OS keychain. Depending on your distribution:

• Debian / Ubuntu: sudo apt-get install libsecret-1-dev
• Red Hat-based: sudo yum install libsecret-devel
• Arch Linux: sudo pacman -S libsecret

Notes

• keytar is a native module; npm install fetches a prebuilt binary for common platforms (Linux / macOS / Windows, x64 / arm64).
• Both tools always run their production build.

License

Released under the MIT license (see LICENSE). Built on top of the Dust CLI and SDK (also MIT). Unofficial; not affiliated with Dust.