Skip to content
Back to search

dutis

MacOS Application Extension Manager

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tsonglew--dutis/badge.svg)](/listings/tsonglew--dutis)

HTML

<a href="/listings/tsonglew--dutis"><img src="/api/listings/tsonglew--dutis/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- macOS 10.14 or later - `duti` (`brew install duti`) when changing default applications; the Homebrew formula installs it automatically

Via Homebrew (Recommended)

brew install tsonglew/tap/dutis

The tap installs universal `dutis` and `dutis-event-http` binaries for Apple Silicon and Intel Macs, together with the `duti` runtime dependency.

Use with coding agents

For requests such as "which app opens PDFs?" or "make VS Code the default for Markdown files", install the [Dutis skill](skills/dutis/SKILL.md) as well as the CLI. Installing Dutis with Homebrew alone does not register the skill with your agent. With Node.js installed, make the skill available to Codex globally:

npx skills add tsonglew/dutis --skill dutis --global --agent codex

For Claude Code, replace `codex` with `claude-code`. Omit `--global` to install for the current project only. The command above installs the latest skill from GitHub; to use the copy bundled with your installed Homebrew release instead:

npx skills add "$(brew --prefix dutis)/share/dutis/skills/dutis" --skill dutis --global --agent codex

Restart the agent session after installation so it can discover the skill. The skill guides the agent through inspection, preview, and verification; it does not install the `dutis` executable. See the [Homebrew guide](docs/homebrew-installation.md) for a direct symlink option. The skill also has a [skills.sh page](https://skills.sh/tsonglew/dutis/dutis) and is available on [ClawHub for OpenClaw users](https://clawhub.ai/tsonglew/skills/dutis).

To expose Dutis as read-only MCP tools, register its local server with your client. For example, for Codex:

codex mcp add dutis -- dutis mcp

For Claude Code and other clients, see the [MCP server guide](docs/mcp-server.md). MCP registration and skill installation are separate: either can be used on its own, and both require the local `dutis` executable. The server advertises write tools only when explicitly enabled.

Install duti

Browsing applications does not require `duti`. To change a default application, install it with:

brew install duti

Manual Installation

Build from Source

# Clone the repository
git clone https://github.com/tsonglew/dutis.git
cd dutis

# Build the project
cargo build --release

# Run the application
cargo run

Install from binary

cargo install --path .

Interactive Mode

Run `dutis` without a subcommand to open the guided terminal menu. It lets you:

1. **Inspect an extension**: See its current default and applications that declare support for it. 2. **Review and change its default**: Compare the current and proposed handlers before an explicit `[y/N]` confirmation. Declining or pressing Enter leaves the system unchanged. 3. **Browse installed applications**: Page through application names, paths, and bundle identifiers without starting a change. 4. **Check readiness**: See scan coverage and whether `duti` is available for mutations. 5. **Discover advanced workflows**: Get direct pointers to typed handlers, recommendations, declarative configuration, snapshots, drift monitoring, and MCP.

Every interactive mutation passes through the same policy, safety snapshot, audit, and post-change verification pipeline as the non-interactive CLI. Every submenu supports a clear path back to the main menu.

When stdin, stdout, and stderr are attached to a capable terminal, Dutis uses a compact keyboard-first interface: arrow keys move the selection, Enter opens it, Esc or `q` returns, and application lists support type-to-filter fuzzy search. When input is piped or the terminal is non-interactive, Dutis automatically falls back to the numbered text interface so scripts and accessibility workflows remain predictable. Set `DUTIS_TUI=plain` to request the text interface explicitly.

Command Line Mode

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 433 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Dutis - macOS Default Application Manager
  2. A Rust application for inspecting and safely managing macOS default handlers for filename extensions, UTIs, MIME types, and URL schemes.
  3. It includes an interactive terminal interface, script-friendly JSON, an agent
  4. skill, and a local MCP server that starts in read-only mode.
  5. **Website:** [English](https://tsonglew.github.io/dutis/) · [中文](https://tsonglew.github.io/dutis/zh-cn/)
  6. [![CI](https://github.com/tsonglew/dutis/actions/workflows/ci.yml/badge.svg)](https://github.com/tsonglew/dutis/actions/workflows/ci.yml)
  7. [![Release](https://github.com/tsonglew/dutis/actions/workflows/release.yml/badge.svg)](https://github.com/tsonglew/dutis/actions/workflows/release.yml)
  8. ## Features
  9. - 🔍 **Scan System Applications**: Automatically discovers all installed applications on macOS
  10. - 📱 **Application Capability Discovery**: Reads declared extensions, UTIs, MIME types, URL schemes, and roles
  11. - 🎯 **Keyboard-first TUI**: Navigate with arrow keys, search applications as you type, and review changes before confirming them
  12. - ⚙️ **Default App Setting**: Set default applications for file types using the `duti` command
  13. - 🧭 **Accurate App Selection**: Preserves full application paths, including nested and duplicate names
  14. - 🧩 **Modern Metadata Support**: Reads legacy document types and modern UTI declarations
  15. - ✅ **Verified Updates**: Verifies the selected default application after applying it
  16. - 🤖 **Agent-ready CLI**: Stable JSON output, dry runs, deterministic selectors, and explicit exit codes
  17. - 📋 **Declarative Configuration**: Plan, diff, apply, and verify a versioned TOML policy
  18. - ↩️ **Snapshots and Rollback**: Persist pre-change state and restore it through the verified plan pipeline
  19. - 🔌 **Local MCP Server**: Give agents read-only discovery and planning tools with separately gated writes
  20. - 🛡️ **Policy and Audit**: Enforce local allowlists and approvals with durable, verified mutation records
  21. - 💡 **Explainable Profiles**: Generate evidence-backed developer, designer, media, or minimal proposals without changing the system
  22. - 🏢 **Fleet-Aware Recommendations**: Apply local allowlists, protected targets, and ordered team preferences before proposing applications
  23. - 🧩 **Profile Overlays**: Extend built-in profiles or add typed team profiles from a strict local configuration
  24. - 👀 **Drift Monitoring**: Detect association changes continuously, notify through macOS, and optionally remediate through snapshots and policy
  25. - 🔗 **Typed Associations**: Manage extensions, UTIs, MIME types, URL schemes, and Launch Services roles through one verified pipeline
  26. - 📡 **Event Sinks**: Stream versioned drift and mutation lifecycle events to private JSONL logs or trusted local commands
  27. - 🌐 **HTTPS Event Adapter**: Forward events with environment-only credentials, bounded retries, and idempotency headers
  28. - 📦 **Durable Event Replay**: Queue failed command deliveries locally and replay them without repeating the original mutation
  29. - 📊 **Delivery Health**: Summarize pending and dead-letter counts without exposing event payloads
  30. - 🍎 **Native Role Inspection**: Read separate viewer, editor, and shell defaults directly from macOS Launch Services
  31. ## Installation
  32. ### Prerequisites
  33. - macOS 10.14 or later
  34. - `duti` (`brew install duti`) when changing default applications; the Homebrew formula installs it automatically
  35. ### Via Homebrew (Recommended)
  36. ```bash
  37. brew install tsonglew/tap/dutis
  38. ```
  39. The tap installs universal `dutis` and `dutis-event-http` binaries for Apple
  40. Silicon and Intel Macs, together with the `duti` runtime dependency.
  41. ### Use with coding agents
  42. For requests such as "which app opens PDFs?" or "make VS Code the default for
  43. Markdown files", install the [Dutis skill](skills/dutis/SKILL.md) as well as
  44. the CLI. Installing Dutis with Homebrew alone does not register the skill with
  45. your agent. With Node.js installed, make the skill available to Codex globally:
  46. ```bash
  47. npx skills add tsonglew/dutis --skill dutis --global --agent codex
  48. ```
  49. For Claude Code, replace `codex` with `claude-code`. Omit `--global` to install
  50. for the current project only. The command above installs the latest skill from
  51. GitHub; to use the copy bundled with your installed Homebrew release instead:
  52. ```bash
  53. npx skills add "$(brew --prefix dutis)/share/dutis/skills/dutis" --skill dutis --global --agent codex
  54. ```
  55. Restart the agent session after installation so it can discover the skill. The
  56. skill guides the agent through inspection, preview, and verification; it does
  57. not install the `dutis` executable. See the [Homebrew guide](docs/homebrew-installation.md)
  58. for a direct symlink option. The skill also has a
  59. [skills.sh page](https://skills.sh/tsonglew/dutis/dutis) and is available on
  60. [ClawHub for OpenClaw users](https://clawhub.ai/tsonglew/skills/dutis).
  61. To expose Dutis as read-only MCP tools, register its local server with your
  62. client. For example, for Codex:
  63. ```bash
  64. codex mcp add dutis -- dutis mcp
  65. ```
  66. For Claude Code and other clients, see the [MCP server guide](docs/mcp-server.md).
  67. MCP registration and skill installation are separate: either can be used on its
  68. own, and both require the local `dutis` executable. The server advertises write
  69. tools only when explicitly enabled.
  70. ### Install duti
  71. Browsing applications does not require `duti`. To change a default application, install it with:
  72. ```bash
  73. brew install duti
  74. ```
  75. ### Manual Installation
  76. ### Build from Source
  77. ```bash
  78. # Clone the repository
  79. git clone https://github.com/tsonglew/dutis.git
  80. cd dutis
  81. # Build the project
  82. cargo build --release
  83. # Run the application
  84. cargo run
  85. ```
  86. ### Install from binary
  87. ```bash
  88. cargo install --path .
  89. ```
  90. ### Interactive Mode
  91. Run `dutis` without a subcommand to open the guided terminal menu. It lets you:
  92. 1. **Inspect an extension**: See its current default and applications that
  93. declare support for it.
  94. 2. **Review and change its default**: Compare the current and proposed
  95. handlers before an explicit `[y/N]` confirmation. Declining or pressing
  96. Enter leaves the system unchanged.
  97. 3. **Browse installed applications**: Page through application names, paths,
  98. and bundle identifiers without starting a change.
  99. 4. **Check readiness**: See scan coverage and whether `duti` is available for
  100. mutations.
  101. 5. **Discover advanced workflows**: Get direct pointers to typed handlers,
  102. recommendations, declarative configuration, snapshots, drift monitoring,
  103. and MCP.
  104. Every interactive mutation passes through the same policy, safety snapshot,
  105. audit, and post-change verification pipeline as the non-interactive CLI. Every
  106. submenu supports a clear path back to the main menu.
  107. When stdin, stdout, and stderr are attached to a capable terminal, Dutis uses a compact
  108. keyboard-first interface: arrow keys move the selection, Enter opens it, Esc or
  109. `q` returns, and application lists support type-to-filter fuzzy search. When
  110. input is piped or the terminal is non-interactive, Dutis automatically falls
  111. back to the numbered text interface so scripts and accessibility workflows
  112. remain predictable. Set `DUTIS_TUI=plain` to request the text interface
  113. explicitly.
  114. ### Command Line Mode
  115. Use explicit commands from shell scripts or AI agents. A leading dot on an
  116. extension is optional.
  117. ```bash
  118. # Inspect installed applications and supported handlers
  119. dutis list
  120. dutis query md
  121. dutis get .md
  122. # Inspect typed Launch Services handlers
  123. dutis handler query uti public.plain-text --role viewer
  124. dutis handler query mime text/plain --role editor
  125. dutis handler query url-scheme https
  126. dutis handler get uti public.plain-text --role viewer
  127. dutis handler get mime text/plain --role editor
  128. dutis handler get url-scheme https
  129. dutis handler defaults extension txt --json
  130. # Emit a versioned JSON response
  131. dutis query json --json
  132. # Preview a change without mutating the system
  133. dutis set md com.microsoft.VSCode --dry-run --json
  134. # Apply and verify a change; --yes is required for non-interactive writes
  135. dutis set md com.microsoft.VSCode --yes
  136. # Preview a typed handler change (URL schemes use the implicit `all` role)
  137. dutis handler set uti public.plain-text com.apple.TextEdit --role viewer --dry-run
  138. dutis handler set url-scheme https com.apple.Safari --yes
  139. # Check local readiness
  140. dutis doctor --json
  141. ```
  142. Manage several associations as one reviewed, idempotent plan:
  143. ```bash
  144. cp dutis.example.toml dutis.toml
  145. dutis plan dutis.toml --json
  146. dutis diff dutis.toml
  147. dutis apply dutis.toml --dry-run
  148. dutis apply dutis.toml --plan-digest <reviewed-digest> --yes
  149. ```
  150. `apply` rebuilds the plan immediately before changing the system and rejects a
  151. stale digest. Every change is verified, unchanged entries are skipped, and
  152. partial failures include a result for every association. See the
  153. [declarative configuration guide](docs/declarative-configuration.md) for the
  154. schema and safety contract.
  155. Typed queries return compact application candidates with the exact matching
  156. Info.plist declarations. Full `list --json` output also includes each
  157. application's registered handlers and imported/exported type definitions. See
  158. [application metadata](docs/application-metadata.md) for evidence and role
  159. matching rules.
  160. Role-specific `handler get` queries and verification use native macOS Launch
  161. Services reads. `handler defaults` returns the complete role matrix. See
  162. [native Launch Services reads](docs/native-launch-services.md).
  163. Create, inspect, and restore local snapshots:
  164. ```bash
  165. dutis snapshot create --config dutis.toml
  166. dutis history
  167. dutis rollback <snapshot-id> --dry-run
  168. dutis rollback <snapshot-id> --yes
  169. ```
  170. Real declarative applies and rollbacks automatically store a safety snapshot
  171. before the first mutation. See [snapshots and rollback](docs/snapshots-and-rollback.md)
  172. for storage, recovery behavior, and the safe limitation around removing an
  173. association.
  174. Run the local MCP server in its default read-only mode:
  175. ```bash
  176. dutis mcp
  177. ```
  178. Mutation tools are registered only with `--allow-writes` and require both a
  179. fresh plan digest and the server-side `DUTIS_MCP_APPROVAL_TOKEN`. See the
  180. [MCP server guide](docs/mcp-server.md) for client configuration, tool schemas,
  181. and the audit contract.
  182. Inspect policy decisions and persistent mutation records:
  183. ```bash
  184. dutis policy show --json
  185. dutis policy check dutis.toml --json
  186. dutis audit --json
  187. ```
  188. Explore built-in profiles and generate a read-only recommendation:
  189. ```bash
  190. dutis profile list
  191. dutis profile show developer --json
  192. dutis recommend developer --json
  193. ```
  194. Customize built-ins or add team profiles with
  195. `$DUTIS_STATE_DIR/profiles.toml` (or `DUTIS_PROFILE_FILE`). Start from
  196. [`dutis.profiles.example.toml`](dutis.profiles.example.toml); overlays support
  197. extensions, UTIs, MIME types, URL schemes, roles, ordered candidates, and
  198. explicit replacement of built-in candidates.
  199. Recommendations use the effective local policy before selecting a target.
  200. Teams can deploy preferences without a remote control plane:
  201. ```toml
  202. [recommendations]
  203. preferred_applications = ["com.microsoft.VSCode"]
  204. [recommendations.extensions]
  205. md = ["com.microsoft.VSCode", "com.apple.TextEdit"]
  206. [[recommendations.handlers]]
  207. kind = "uti"
  208. identifier = "public.plain-text"
  209. role = "viewer"
  210. applications = ["com.apple.TextEdit", "com.microsoft.VSCode"]
  211. [[recommendations.handlers]]
  212. kind = "url_scheme"
  213. identifier = "vscode"
  214. applications = ["com.microsoft.VSCode"]
  215. ```
  216. Results show each candidate's source, policy eligibility, installed paths,
  217. declared target support, the proposed TOML, a deterministic plan digest, and
  218. the effective policy assessment. Typed UTI, MIME, and URL-scheme preferences
  219. require an exact compatible declaration from the installed application. They
  220. never change system associations.
  221. Review [profiles and recommendations](docs/profiles-and-recommendations.md) for
  222. selection rules and the safe path from a proposal to an approved apply.
  223. Check a declared configuration once or monitor it continuously:
  224. ```bash
  225. dutis watch dutis.toml --once --json
  226. dutis watch dutis.toml --interval-seconds 60 --notify
  227. ```
  228. Install an optional per-user LaunchAgent that keeps the monitor running:
  229. ```bash
  230. dutis launch-agent install dutis.toml --interval-seconds 300 --notify
  231. dutis launch-agent status
  232. ```
  233. Monitoring is read-only by default. Automatic remediation requires
  234. `--remediate --yes --requester <identity>` and always passes through policy,
  235. audit, safety snapshot, apply, and verification. See
  236. [drift detection](docs/drift-detection.md).
  237. Send drift and mutation lifecycle events to automation without parsing human
  238. output:
  239. ```bash
  240. dutis --event-log ./dutis-events.jsonl watch dutis.toml --once --json
  241. dutis --event-command /absolute/path/to/event-handler apply dutis.toml \
  242. --plan-digest <reviewed-digest> --requester codex --yes
  243. ```
  244. Event options are global and can appear before or after a subcommand. The same
  245. settings can be provided through `DUTIS_EVENT_LOG`, `DUTIS_EVENT_COMMAND`, and
  246. `DUTIS_EVENT_OUTBOX`. See [event sinks](docs/event-sinks.md) for the schema,
  247. command contract, LaunchAgent behavior, and delivery guarantees.
  248. To forward events over HTTPS without placing credentials in Dutis arguments,
  249. configuration, or audit records, use the bundled
  250. [`dutis-event-http`](docs/http-event-adapter.md) command:
  251. ```bash
  252. export DUTIS_HTTP_ENDPOINT='https://events.example.com/hooks/dutis'
  253. export DUTIS_HTTP_BEARER_TOKEN='replace-with-a-scoped-token'
  254. export DUTIS_EVENT_COMMAND="$(command -v dutis-event-http)"
  255. dutis-event-http --check --json
  256. # Inspect and replay failed command deliveries
  257. dutis events health --json
  258. dutis events pending --json
  259. dutis events replay --limit 100 --json
  260. dutis events archive --max-attempts 5 --older-than-days 30 --json
  261. dutis events archive --max-attempts 5 --older-than-days 30 --yes
  262. dutis events dead-letters --json
  263. dutis events purge --older-than-days 90 --json
  264. dutis events purge --older-than-days 90 --yes
  265. ```
  266. Failed event-command deliveries are stored automatically under the Dutis state
  267. directory. Override that location with `--event-outbox` or
  268. `DUTIS_EVENT_OUTBOX`. Replay keeps the original event ID so remote consumers
  269. can deduplicate retries. See [durable event replay](docs/event-replay.md).
  270. Archive and purge commands are previews unless `--yes` is present, so pending
  271. deliveries are never removed by an implicit retention policy.
  272. `events health` is read-only and reports stable counts, retry totals, time
  273. ranges, and type/source breakdowns without event IDs or payload contents. The
  274. same summary is available to read-only MCP clients as `dutis_event_health`.
  275. All write paths enforce the same local policy before mutation and record the
  276. requester, reviewed plan, result, and verification. See the
  277. [policy and audit guide](docs/policy-and-audit.md). A reusable agent workflow is
  278. included at [`skills/dutis/SKILL.md`](skills/dutis/SKILL.md).
  279. Homebrew installs it under `$(brew --prefix dutis)/share/dutis/skills/dutis`.
  280. Applications can be selected by exact bundle ID, exact application path, or an
  281. unambiguous application name. JSON responses use API version `1`. Exit codes are
  282. `0` for success, `2` for usage errors, `3` for no match, `4` for ambiguous
  283. selectors, `5` for an unavailable dependency, and `6` for operation failure.
  284. Declarative apply uses `7` for a stale plan. Apply and event replay use `8` for
  285. partial failure.
  286. Policy denial uses exit code `9`.
  287. The product and engineering sequence for declarative configuration, rollback,
  288. MCP, agent policies, profiles, drift detection, and event delivery is documented in the
  289. [Agent Roadmap](docs/agent-roadmap.md).
  290. ## How It Works
  291. ### Application Scanning
  292. 1. **System Directories**: Scans `/Applications`, `/System/Applications`, and `~/Applications`
  293. 2. **Info.plist Parsing**: Reads document types, URL types, roles, extensions, UTIs, and MIME types
  294. 3. **Modern Metadata**: Keeps handler registrations separate from exported and imported UTI definitions
  295. ### Default App Setting
  296. 1. **Bundle ID Detection**: Reads the selected application's bundle identifier
  297. 2. **duti Integration**: Sets extension, UTI, MIME, and URL-scheme handlers with the requested Launch Services role
  298. 3. **Verification**: Reads the resulting association back before reporting success
  299. ## Technical Details
  300. ### Architecture
  301. - **Modular Design**: Separates application scanning and plist parsing from the interactive flow
  302. - **macOS Native**: Works with application bundles and Launch Services through `duti`
  303. - **Error Handling**: Comprehensive error handling using `anyhow`
  304. ### Dependencies
  305. - **anyhow**: Error handling and propagation
  306. - **colored**: Terminal output formatting and colors
  307. - **dialoguer**: Keyboard navigation, searchable selectors, and confirmations
  308. - **plist**: Native XML and binary plist parsing
  309. - **clap**: Command parsing and generated help
  310. - **serde / serde_json**: Versioned machine-readable output
  311. - **toml**: Strict declarative configuration parsing
  312. - **sha2**: Deterministic reviewed-plan digests
  313. - **time**: Portable RFC 3339 snapshot timestamps
  314. ## Releases
  315. After a version bump is merged into `master`, CI validates the commit, creates the matching version tag, publishes a universal macOS binary and checksum, then updates the `tsonglew/homebrew-tap` repository. Maintainer setup and release instructions are documented in [docs/releasing.md](docs/releasing.md).
  316. ## Contributing
  317. Contributions are welcome! Please feel free to submit a Pull Request.
  318. ## Community
  319. ### Star History
  320. [![Dutis Star History](https://tsonglew.github.io/dutis/star-history.svg)](https://tsonglew.github.io/dutis/star-history.svg)
  321. The chart is regenerated daily by GitHub Actions using an ephemeral repository
  322. token; no personal access token or individual stargazer identity is published.
  323. ### Contributors
  324. [![Contributors](https://contrib.rocks/image?repo=tsonglew/dutis)](https://github.com/tsonglew/dutis/graphs/contributors)
  325. ## License
  326. This project is licensed under the MIT License.
  327. ## Support
  328. If you encounter any issues or have questions, please create an issue on GitHub.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.