cli commands/run

39 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

deno run basic usage

The deno run subcommand executes a JavaScript or TypeScript program. The run subcommand is optional; you can also just use deno <file>.

deno run default sandbox behavior

By default, Deno runs programs in a sandbox without access to disk, network, or ability to spawn subprocesses. This is because the Deno runtime is secure by default.

deno run permission flags

Permissions can be granted or denied using --allow-* and --deny-* flags. The -A flag grants all permissions but is not recommended and should only be used for testing.

deno run specific permission example

To grant permission to read from specific file paths, use --allow-read=/path syntax, for example: deno run --allow-read=/etc server.ts

deno run --watch flag

The --watch flag enables file watching to restart the process automatically when files are changed. The flag must be placed before the file name, for example: deno run --allow-net --watch server.ts

deno run --watch restart behavior in Deno 2.8

When the watcher restarts the process in Deno 2.8, it sends SIGTERM first so unload event listeners and process.exit hooks run, then waits 500ms before the hard kill. This gives graceful-shutdown code time to flush resources between restarts.

deno run --watch available for other commands

The --watch flag is also accepted by deno test, deno serve, and deno bench commands.

deno run from stdin

Code can be piped from stdin and run immediately by using a hyphen as the file argument, for example: echo "console.log('hello')" | deno run -

deno run termination

To stop the run command, use Ctrl+C.

--ts flag replaced with --ext=ts

The --ts and -T CLI flags have been replaced with --ext=ts. Use deno run --ext=ts script.ts instead of deno run --ts script.ts or deno run -T script.ts.

--allow-all flag

The --allow-all flag (shorthand: -A) grants all permissions to a script and disables the security sandbox entirely. Usage: deno run -A script.ts or deno run --allow-all script.ts. This has the same security properties as running a script in Node.js.

--allow-read flag and -R shorthand

The --allow-read flag (shorthand: -R) grants permission to read files and directories. Syntax: --allow-read[=<PATH>...] or -R[=<PATH>...]. PATHs may be separated by comma (,) characters; to include a comma in a PATH, double it. Examples: deno run -R script.ts (allow all reads), deno run --allow-read=foo.txt,bar.txt script.ts (allow specific files), deno run --allow-read=node_modules script.ts (allow reads from directory and subdirectories).

--deny-read flag

The --deny-read flag denies read access to specific paths and takes precedence over --allow-read flags. Syntax: --deny-read[=<PATH>...]. Examples: deno run --allow-read=/etc --deny-read=/etc/hosts script.ts (allow /etc but deny /etc/hosts), deno run --deny-read script.ts (deny all read access and disable permission prompts).

--allow-write flag and -W shorthand

The --allow-write flag (shorthand: -W) grants permission to write files and directories. Syntax: --allow-write[=<PATH>...] or -W[=<PATH>...]. PATHs may be separated by comma characters. Examples: deno run -W script.ts (allow all writes), deno run --allow-write=foo.txt,bar.txt script.ts (allow writes to specific files).

--deny-write flag

The --deny-write flag denies write access to specific paths and takes precedence over --allow-write flags. Syntax: --deny-write[=<PATH>...]. Examples: deno run --allow-write=./ --deny-write=./secrets script.ts (allow writes to current directory but deny ./secrets), deno run --deny-write script.ts (deny all write access and disable permission prompts).

APIs that use file system operations without explicit permissions

Some APIs in Deno are implemented using file system operations but do not require explicit read/write permissions: localStorage, Deno KV, caches, and Blob. These APIs can consume file system resources like storage space even without direct file system access permissions.

Module loading default read permissions

During module loading, Deno allows certain file reads by default: All files imported from the entrypoint module that can be statically analyzed are allowed by default, including static import statements and dynamic import() calls with string literal arguments. The full list can be printed using deno info <entrypoint>. Files dynamically imported in ways that cannot be statically analyzed require runtime read permissions. Web Worker scripts loaded as local files require --allow-read. Worker scripts loaded from https: URLs require --allow-import instead. Files inside node_modules/ directories are allowed to be read by default.

Symbolic link permission rules

When reading or writing through a symbolic link, Deno checks permissions based on the symlink's location, not the target. For example, --allow-read=/app allows reading through /app/link even if it points outside /app. However, Deno prevents privilege escalation through symlinks: reading/writing through symlinks to /proc, /dev, /sys (Linux) requires --allow-all; /proc/**/environ requires --allow-env; /dev/null, /dev/zero, /dev/random, /dev/urandom are always accessible without additional permissions. Creating symlinks with Deno.symlink() requires both --allow-read and --allow-write with full access (not path-specific).

--allow-net flag and -N shorthand

The --allow-net flag (shorthand: -N) grants permission to make network requests, open listeners, and perform DNS resolution. Syntax: --allow-net[=<HOST>...] or -N[=<HOST>...]. Hostnames do not allow subdomains unless explicitly listed; use * as a wildcard for any subdomain. Examples: deno run -N script.ts (allow all network), deno run --allow-net=github.com,jsr.io script.ts (specific hosts), deno run --allow-net="*.example.com" script.ts (all subdomains), deno run --allow-net=example.com:80 script.ts (hostname with port), deno run --allow-net=1.1.1.1:443 script.ts (IPv4 with port), deno run --allow-net=[2606:4700:4700::1111] script.ts (IPv6 address).

--deny-net flag

The --deny-net flag denies network access to specific hosts and takes precedence over --allow-net flags. Syntax: --deny-net[=<HOST>...]. Examples: deno run --allow-net --deny-net=github.com,jsr.io script.ts (allow network but deny specific hosts), deno run --deny-net script.ts (deny all network access and disable permission prompts).

Default trusted hosts for module loading

By default, Deno allows loading modules from the following locations without requiring explicit network access: https://deno.land/, https://jsr.io/, https://esm.sh/, https://raw.esm.sh/, https://cdn.jsdelivr.net/, https://raw.githubusercontent.com/, https://gist.githubusercontent.com/. These are trusted public registries not expected to enable data exfiltration. Deno also allows importing any NPM package through npm: specifiers by default.

--allow-env flag and -E shorthand

The --allow-env flag (shorthand: -E) grants permission to read and write environment variables. Syntax: --allow-env[=<VARIABLE_NAME>...] or -E[=<VARIABLE_NAME>...]. Starting with Deno v2.1, you can specify suffix wildcards to allow scoped access. Examples: deno run -E script.ts (allow all environment variables), deno run --allow-env=HOME,FOO script.ts (specific variables), deno run --allow-env="AWS_*" script.ts (variables starting with AWS_).

--deny-env flag

The --deny-env flag denies access to specific environment variables and takes precedence over --allow-env flags. Syntax: --deny-env[=<VARIABLE_NAME>...]. Examples: deno run --allow-env --deny-env=AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY script.ts (allow env but deny specific variables), deno run --deny-env script.ts (deny all environment variable access and disable permission prompts).

--ignore-env flag

The --ignore-env flag silently returns undefined for environment variable reads instead of denying access outright. This is useful when you want code to run without failing on missing permissions, treating restricted variables as unset. Syntax: --ignore-env[=<VARIABLE_NAME>...]. Examples: deno run --ignore-env script.ts (ignore all environment variables), deno run --ignore-env=PORT,HOME script.ts (ignore specific variables).

NO_COLOR environment variable visibility

The value of the NO_COLOR environment variable is visible to all code running in the Deno runtime, regardless of whether the code has been granted permission to read environment variables.

--allow-sys flag and -S shorthand

The --allow-sys flag (shorthand: -S) grants permission to access system information such as OS release, uptime, load average, network interfaces, and memory info. Syntax: --allow-sys[=<API_NAME>...] or -S[=<API_NAME>...]. API names can be specified from the list in Deno.SysPermissionDescriptor. Examples: deno run -S script.ts (allow all system information), deno run --allow-sys="systemMemoryInfo,osRelease" script.ts (specific APIs). Recognized API names include hostname, osRelease, osUptime, loadavg, networkInterfaces, systemMemoryInfo, uid, gid, username, cpus, and homedir.

--deny-sys flag

The --deny-sys flag denies access to specific system information APIs and takes precedence over --allow-sys flags. Syntax: --deny-sys[=<API_NAME>...]. Examples: deno run --allow-sys --deny-sys="networkInterfaces" script.ts (allow system info but deny networkInterfaces), deno run --deny-sys script.ts (deny all system information access and disable permission prompts).

--allow-sys maps to Node compatibility APIs

The same --allow-sys flag gates Node-compatibility APIs. Functions in node:os and node:process that read system information require --allow-sys with the corresponding interface name. Examples: os.cpus() needs --allow-sys=cpus, os.networkInterfaces() needs --allow-sys=networkInterfaces, os.hostname() needs --allow-sys=hostname, os.freemem()/os.totalmem()/os.uptime() need --allow-sys, process.getuid()/process.getgid() need --allow-sys with uid/gid respectively.

--allow-run flag

The --allow-run flag grants permission to spawn subprocesses. Syntax: --allow-run[=<PROGRAM_NAME>...]. When limited to specific program names, only those programs can be executed. Examples: deno run --allow-run script.ts (allow all subprocesses), deno run --allow-run="curl,whoami" script.ts (allow specific programs).

Subprocess privilege escalation warning

Any subprocesses spawned from a Deno program run independently from the parent's permissions, meaning child processes can access system resources regardless of parent permissions. This is privilege escalation. Granting --allow-run essentially invalidates the Deno security sandbox. Do not use --allow-run=deno unless the parent process has --allow-all, as spawning a deno process means the script can spawn another deno process with full permissions.

Sending signals to own process without --allow-run

Sending a signal to your own process does not require --allow-run, since it is equivalent to terminating yourself. Deno.kill(Deno.pid, ...) and process.kill(process.pid, ...) work without the flag, so tools that re-raise a signal on their own PID (such as signal-exit, used by Vite) do not force blanket run access.

LD_* and DYLD_* environment variables require unscoped --allow-run

Spawning a subprocess with environment variables starting with LD_ (such as LD_LIBRARY_PATH, LD_PRELOAD) or DYLD_ (such as DYLD_LIBRARY_PATH, DYLD_INSERT_LIBRARIES) requires the unscoped --allow-run flag. Scoped allow lists like --allow-run=curl are insufficient, even if the value matches Deno's startup value. These variables instruct the dynamic linker to load arbitrary shared libraries into the child process, bypassing executable restrictions.

--deny-run flag

The --deny-run flag denies permission to spawn specific subprocesses and takes precedence over --allow-run flags. Syntax: --deny-run[=<PROGRAM_NAME>...]. Examples: deno run --allow-run --deny-run="whoami,ps" script.ts (allow running most programs but deny specific ones), deno run --deny-run script.ts (deny all subprocess spawning and disable permission prompts).

--allow-scripts flag for npm package post-install scripts

By default, npm packages will not have their post-install scripts executed during installation (like with deno install), as this would allow arbitrary code execution. When running with the --allow-scripts flag, post-install scripts for npm packages will be executed as a subprocess.

--allow-ffi flag

The --allow-ffi flag grants permission to use the Deno.dlopen API to load shared libraries and call functions from them. It also allows NAPI native addons. Syntax: --allow-ffi[=<PATH>...]. Path-specific restrictions can be applied to limit which dynamic libraries can be loaded. Examples: deno run --allow-ffi script.ts (allow loading all libraries), deno run --allow-ffi=./libfoo.so script.ts (allow loading from specific path). Dynamic libraries are not run in a sandbox and do not have security restrictions of the Deno process, so use with extreme caution.

--deny-ffi flag

The --deny-ffi flag denies permission to load specific dynamic libraries and takes precedence over --allow-ffi flags. Syntax: --deny-ffi[=<PATH>...]. Examples: deno run --allow-ffi --deny-ffi=./libfoo.so script.ts (allow loading all libraries except ./libfoo.so), deno run --deny-ffi script.ts (deny loading all dynamic libraries and disable permission prompts).

--allow-import flag for importing from web

The --allow-import flag grants permission to dynamically import code from HTTP and HTTPS URLs. Syntax: --allow-import[=<HOST>...]. Examples: deno run --allow-import=example.com main.ts (allow importing from specific host), deno run --allow-import main.ts (allow importing from default trusted hosts). By default, importing from specific hosts requires this flag, but importing from trusted public registries is allowed by default. Specifying an allow list for --allow-import will override the default hosts list.

--deny-import flag

The --deny-import flag blocks importing code from specific hosts, even when they would otherwise be allowed. Deny flags take precedence over allow flags. Syntax: --deny-import[=<HOST>...]. Example: deno run --deny-import=esm.sh main.ts (allow default import hosts except esm.sh).

--no-prompt flag

The --no-prompt flag disables runtime permission prompts. Prompts are also not shown if stdout/stderr are not a TTY.

Give your agent this brain