@happycoding-ai/dsh-fakecmd

Cargo-style fake subcommands and profile shorthand for the DeepSeek Harness (dsh) CLI.

dsh-fakecmd is a CLI wrapper / launcher shim. It does not modify DSH itself and does not install a DSH plugin. The DSH-oriented entrypoint remains dshx; fakecmd is only a short alias for the longer dsh-fakecmd command.

The wrapper has two jobs:

1. Profile shorthand — write dshx research ..., or dsh research ... after setup-shim, instead of dsh --profile research ....
2. Fake subcommands — let developers provide Cargo-style external executables such as dsh-deploy, then call them as dshx deploy ..., or dsh deploy ... after setup-shim.

For external mode, the only contract is: an executable named dsh-<name> must be discoverable from PATH. It does not require npm, pnpm, a DSH manifest, or a registry entry.

Install

npm install -g @happycoding-ai/dsh-fakecmd

The package intentionally exposes only non-conflicting bins:

• dshx — DSH-oriented short entrypoint; existing behavior stays unchanged.
• dsh-fakecmd — long-form explicit entrypoint.
• fakecmd — short alias for dsh-fakecmd.

It intentionally does not publish a dsh bin, because the official @deepseek-ai/dsh package already owns that command. Publishing another global dsh bin makes normal npm install -g fail with EEXIST when DSH is installed first.

After install, verify:

command -v dsh
command -v dshx
command -v dsh-fakecmd
command -v fakecmd
dshx -h

If dsh is installed in the same active Node/npm environment, dshx normally finds and delegates to it automatically. If not, set the real DSH path explicitly when you run fakecmd:

DSH_FAKECMD_REAL_DSH="/absolute/path/to/original/dsh" dshx -h

Usage

# Profile mode:
dshx research "summarize this repo"
# runs: real-dsh --profile research "summarize this repo"

# External mode:
dshx deploy --force
# searches PATH for dsh-deploy, then runs: dsh-deploy --force

# Native dsh mode:
dshx plugin --profile web list
# passes through unchanged to the real dsh

fakecmd is just a shorter way to type dsh-fakecmd:

dsh-fakecmd setup-shim
fakecmd setup-shim

dshx still works exactly the same way:

dshx research "summarize this repo"
dshx deploy --force

Optional transparent dsh mode

Transparent dsh <name> interception is possible, but it is a shell/PATH decision, not something an npm package can guarantee safely while official DSH also owns dsh.

Use the explicit setup command when you want transparent mode:

dshx setup-shim
# equivalent long/short maintenance aliases:
dsh-fakecmd setup-shim
fakecmd setup-shim

setup-shim does three things:

1. Finds the real official dsh executable.
2. Creates a private shim under $HOME/.dsh-fakecmd/bin.
3. Prints or writes the PATH instruction needed for transparent dsh ... mode.

macOS / Linux

On bash or zsh, setup-shim creates $HOME/.dsh-fakecmd/bin/dsh and adds an idempotent managed PATH block to ~/.bashrc or ~/.zshrc when it can identify the shell.

Open a new shell, or run this once in the current shell:

export PATH="$HOME/.dsh-fakecmd/bin:$PATH"

Verify:

command -v dsh
# expected: /home/you/.dsh-fakecmd/bin/dsh

dsh research "summarize this repo"
dsh deploy --force

Windows

On Windows, setup-shim creates %USERPROFILE%\.dsh-fakecmd\bin\dsh.cmd. It does not silently edit the registry or persistent user Path; it prints the commands to use.

PowerShell current session:

$env:Path = "$env:USERPROFILE\.dsh-fakecmd\bin;$env:Path"

cmd.exe current session:

set "PATH=%USERPROFILE%\.dsh-fakecmd\bin;%PATH%"

For persistent transparent mode, add %USERPROFILE%\.dsh-fakecmd\bin before the official DSH directory in the user Path environment variable.

If the real dsh is in a different Node/nvm environment, pass it once during setup; the generated shim will remember it:

DSH_FAKECMD_REAL_DSH="/absolute/path/to/original/dsh" dshx setup-shim

If command -v dsh / where dsh still prints the official DSH path first, fakecmd is not intercepting; shell lookup reached official DSH first.

Routing model

When you run:

dshx <name> [...args]

(or dsh-fakecmd <name> [...args], fakecmd <name> [...args], or optional transparent dsh <name> [...args]), fakecmd resolves <name> in this order:

1. Native dsh mode — if the invocation is already a native dsh command or option, fakecmd passes it through to the real dsh unchanged.
   • Examples: dshx web, dshx plugin --profile web list, dshx --profile headless "hello", dshx --help.
2. Profile mode — if <name> is a known DSH profile, fakecmd runs the real dsh as dsh --profile <name> [...args].
   • Known profiles include shipped templates such as web / headless and initialized profile directories under $DSH_HOME/profiles/<name>/package.json.
   • If a profile and an external command have the same name, the profile wins because profile mode is resolved before external mode.
3. External mode — if <name> is not a profile, fakecmd constructs the command name dsh-<name>, searches for it on PATH, and executes it with the remaining args.
   • This is plain executable lookup. Any executable file named dsh-xxx works when it can be found from PATH: npm/pnpm/yarn global bin, shell script, Node script with a shebang, Python script, Go/Rust binary, symlink, or a manually copied executable.
   • Unix/macOS rule: put an executable file such as dsh-deploy in any directory listed in $PATH; the file must have execute permission.
   • Windows rule: put an executable file such as dsh-deploy.exe, dsh-deploy.cmd, dsh-deploy.bat, or another extension from PATHEXT in any directory listed in Path / PATH.
   • No npm-specific behavior is required. Package managers are only a convenient way to place a dsh-<name> executable on PATH.
4. Error mode — if neither a profile nor a dsh-<name> executable exists, fakecmd prints available profiles and a hint for creating/installing the external command.

Developer extension model

To add a new fake subcommand, put any executable named dsh-<name> on the user's PATH.

Minimal Unix/macOS example:

cat > /usr/local/bin/dsh-hello <<'SH'
#!/usr/bin/env sh
echo "hello from fakecmd: $*"
SH
chmod +x /usr/local/bin/dsh-hello

dshx hello world
# hello from fakecmd: world

Minimal Windows example:

:: place this as dsh-hello.cmd in a directory included in Path
@echo off
echo hello from fakecmd: %*

An npm package can also expose the same executable name:

{
  "name": "@your-scope/dsh-deploy",
  "bin": {
    "dsh-deploy": "./bin/dsh-deploy.js"
  }
}

After installation, users can run:

dshx deploy --force
# or, if optional transparent mode is configured:
dsh deploy --force

The external executable receives only the args after <name>; for dshx deploy --force, it receives --force.

Built-in setup command

setup-shim is intentionally explicit. It is not run from postinstall, because npm install hooks should not silently rewrite shell startup files, edit persistent Path, or shadow official commands.

dshx setup-shim

Re-run it whenever the real dsh path changes, for example after switching Node versions and reinstalling DSH.

Local development

From this repository, build and link the bins:

pnpm build
npm link

Then verify the linked bins are the active development build:

command -v dshx
dshx research "summarize this repo"
dshx deploy --force
fakecmd setup-shim

To verify the packed npm artifact exactly as a user would install it, run:

pnpm build
pnpm verify:install

That smoke test packs the project, installs the tarball into a temporary npm project, proves profile mode, external dsh-* mode, fakecmd alias, and setup-shim transparent mode work from the installed bins, and verifies the package can coexist with an already-installed dsh binary.

Environment variables

• DSH_HOME: DSH home directory; defaults to ~/.dsh.
• DSH_FAKECMD_REAL_DSH: absolute path to the real dsh; useful when active Node/npm environments differ or when optional transparent dsh mode is configured.

Repository

GitHub: https://github.com/photowey/dsh-fakecmd