Command Line Interface

Deno is a command line program. The Deno command line interface (CLI) can be used to run scripts, manage dependencies, and even compile your code into standalone executables. You may be familiar with some simple commands having followed the examples thus far. This page will provide a more detailed overview of the Deno CLI.

The Deno CLI has a number of subcommands (like run, init and test, etc.). They are used to perform different tasks within the Deno runtime environment. Each subcommand has its own set of flags and options (eg --version) that can be used to customize its behavior.

You can view all of the available commands and flags by running the deno help subcommand in your terminal, or using the -h or --help flags.

Check out the CLI reference guide for a further documentation on all the subcommands and flags available. We'll take a look at a few commands in a bit more detail below to see how they can be used and configured.

An example subcommand - deno run Jump to heading#

You can run a local TypeScript or JavaScript file by specifying its path relative to the current working directory:

deno run main.ts

Deno supports running scripts directly from URLs. This is particularly useful for quickly testing or running code without downloading it first:

deno run https://docs.deno.com/examples/hello-world.ts

You can also run a script by piping it through standard input. This is useful for integrating with other command-line tools or dynamically generating scripts:

cat main.ts | deno run -

Passing script arguments Jump to heading#

Script arguments are additional parameters you can pass to your script when running it from the command line. These arguments can be used to customize the behavior of your program based on the input provided at runtime. Arguments should be passed after the script name.

To test this out we can make a script that will log the arguments passed to it:

console.log(Deno.args);

When we run that script and pass it some arguments it will log them to the console:

$ deno run main.ts arg1 arg2 arg3
[ "arg1", "arg2", "arg3" ]

Argument and flag ordering Jump to heading#

Note that anything passed after the script name will be passed as a script argument and not consumed as a Deno runtime flag. This leads to the following pitfall:

# Good. We grant net permission to net_client.ts.
deno run --allow-net net_client.ts

# Bad! --allow-net was passed to Deno.args, throws a net permission error.
deno run net_client.ts --allow-net

Common flags Jump to heading#

Some flags can be used with multiple related subcommands. We discuss these below.

Watch mode Jump to heading#

You can supply the --watch flag to deno run, deno test, deno compile, and deno fmt to enable the built-in file watcher. The watcher enables automatic reloading of your application whenever changes are detected in the source files. This is particularly useful during development, as it allows you to see the effects of your changes immediately without manually restarting the application.

The files that are watched will depend on the subcommand used:

• for deno run, deno test, and deno compile the entrypoint, and all local files that the entrypoint statically imports will be watched.
• for deno fmt all local files and directories specified as command line arguments (or the working directory if no specific files/directories is passed) are watched.

deno run --watch main.ts
deno test --watch
deno fmt --watch

You can exclude paths or patterns from watching by providing the --watch-exclude flag. The syntax is --watch-exclude=path1,path2. For example:

deno run --watch --watch-exclude=file1.ts,file2.ts main.ts

This will exclude file1.ts and file2.ts from being watched.

To exclude a pattern, remember to surround it in quotes to prevent your shell from expanding the glob:

deno run --watch --watch-exclude='*.js' main.ts

Hot Module Replacement mode Jump to heading#

You can use --watch-hmr flag with deno run to enable the hot module replacement mode. Instead of restarting the program, the runtime will try to update the program in-place. If updating in-place fails, the program will still be restarted.

deno run --watch-hmr main.ts

When a hot module replacement is triggered, the runtime will dispatch a CustomEvent of type hmr that will include path property in its detail object. You can listen for this event and perform any additional logic that you need to do when a module is updated (eg. notify a browser over a WebSocket connection).

addEventListener("hmr", (e) => {
  console.log("HMR triggered", e.detail.path);
});

Integrity flags (lock files) Jump to heading#

Affect commands which can download resources to the cache: deno cache, deno run, deno test, deno doc, and deno compile.

--lock <FILE>    Check the specified lock file
--lock-write     Write lock file. Use with --lock.

Find out more about these here.

Cache and compilation flags Jump to heading#

Affect commands which can populate the cache: deno cache, deno run, deno test, deno doc, and deno compile. As well as the flags above, this includes those which affect module resolution, compilation configuration etc.

--config <FILE>               Load configuration file
--import-map <FILE>           Load import map file
--no-remote                   Do not resolve remote modules
--reload=<CACHE_BLOCKLIST>    Reload source code cache (recompile TypeScript)
--unstable                    Enable unstable APIs

Runtime flags Jump to heading#

Affect commands which execute user code: deno run and deno test. These include all of the above as well as the following.

Type checking flags Jump to heading#

You can type-check your code (without executing it) using the command:

> deno check main.ts

You can also type-check your code before execution by using the --check argument to deno run:

> deno run --check main.ts

This flag affects deno run, deno eval, deno repl and deno cache. The following table describes the type-checking behavior of various subcommands. Here "Local" means that only errors from local code will induce type-errors, modules imported from https URLs (remote) may have type errors that are not reported. (To turn on type-checking for all modules, use --check=all.)

Permission flags Jump to heading#

These are listed here.

Other runtime flags Jump to heading#

More flags which affect the execution environment.

--cached-only                Require that remote dependencies are already cached
--inspect=<HOST:PORT>        activate inspector on host:port ...
--inspect-brk=<HOST:PORT>    activate inspector on host:port and break at ...
--inspect-wait=<HOST:PORT>   activate inspector on host:port and wait for ...
--location <HREF>            Value of 'globalThis.location' used by some web APIs
--prompt                     Fallback to prompt if required permission wasn't passed
--seed <NUMBER>              Seed Math.random()
--v8-flags=<v8-flags>        Set V8 command line options. For help: ...