Skip to content

docs: rewrite getting started pages for a better first 5 minutes #3008

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bartlomieju wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: rewrite getting started pages for a better first 5 minutes #3008

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
240 changes: 53 additions & 187 deletions runtime/getting_started/command_line_interface.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,234 +1,100 @@
---
title: Command line interface
description: "A comprehensive guide to using Deno's command-line interface (CLI). Learn about running scripts, managing permissions, using watch mode, and configuring Deno's runtime behavior through command-line flags and options."
description: "An overview of Deno's command-line interface: running scripts, common flags, and key subcommands."
oldUrl:
- /manual/getting_started/command_line_interface
- /runtime/manual/getting_started/command_line_interface/
- /runtime/fundamentals/command_line_interface/
- /runtime/manual/tools/
---

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](/runtime/reference/cli/) 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`

You can run a local TypeScript or JavaScript file by specifying its path
relative to the current working directory:
The Deno CLI lets you run scripts, manage dependencies, run tests, format code,
and more. You can view all available commands by running:

```shell
deno run main.ts
deno help
```

Deno supports running scripts directly from URLs. This is particularly useful
for quickly testing or running code without downloading it first:
For detailed documentation on every subcommand and flag, see the
[CLI reference guide](/runtime/reference/cli/).

```shell
deno run https://docs.deno.com/examples/scripts/hello_world.ts
```
## Running scripts

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:
Run a local TypeScript or JavaScript file:

```shell
cat main.ts | deno run -
```

## Passing script arguments

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:

```ts title="main.ts"
console.log(Deno.args);
deno run main.ts
```

When we run that script and pass it some arguments it will log them to the
console:
You can also pipe code from stdin:

```shell
$ deno run main.ts arg1 arg2 arg3
[ "arg1", "arg2", "arg3" ]
cat main.ts | deno run -
```

## Argument and flag ordering
## Permissions

_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:
By default, Deno runs programs in a sandbox without access to disk, network, or
environment. Use `--allow-*` flags to grant access:

```shell
# Good. We grant net permission to net_client.ts.
deno run --allow-net net_client.ts
# Allow network and file read access
deno run --allow-net --allow-read server.ts

# Bad! --allow-net was passed to Deno.args, throws a net permission error.
deno run net_client.ts --allow-net
# Grant all permissions (not recommended for production)
deno run -A server.ts
```

## Common flags

Some flags can be used with multiple related subcommands. We discuss these
below.
Learn more about [permissions and security](/runtime/fundamentals/security/).

### Watch mode

You can supply the `--watch` flag to `deno run`, `deno test`, 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` and `deno test` 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.

```shell
deno run --watch main.ts
deno test --watch
deno fmt --watch
```
## Script arguments

You can exclude paths or patterns from watching by providing the
`--watch-exclude` flag. The syntax is `--watch-exclude=path1,path2`. For
example:
Arguments passed **after** the script name are available via `Deno.args`:

```shell
deno run --watch --watch-exclude=file1.ts,file2.ts main.ts
$ deno run main.ts arg1 arg2 arg3
[ "arg1", "arg2", "arg3" ]
```

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

To exclude a pattern, remember to surround it in quotes to prevent your shell
from expanding the glob:
Deno flags must come _before_ the script name. Anything after the script name is
treated as a script argument, not a Deno flag:

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

### Hot Module Replacement mode

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.

```sh
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).

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

### Integrity flags (lock files)

Affect commands which can download resources to the cache: `deno install`,
`deno run`, `deno test`, `deno doc`, and `deno compile`.
# Good — grants net permission
deno run --allow-net server.ts

```sh
--lock <FILE> Check the specified lock file
--frozen[=<BOOLEAN>] Error out if lockfile is out of date
# Bad — --allow-net is passed to Deno.args instead
deno run server.ts --allow-net
```

Find out more about these
[here](/runtime/fundamentals/modules/#integrity-checking-and-lock-files).
:::

### Cache and compilation flags
## Watch mode

Affect commands which can populate the cache: `deno install`, `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.

```sh
--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)
```

### Runtime flags

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

You can type-check your code (without executing it) using the command:
Use `--watch` to automatically restart on file changes during development:

```shell
> deno check main.ts
```

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

```shell
> deno run --check main.ts
deno run --watch server.ts
deno test --watch
```

This flag affects `deno run` and `deno eval`. 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`.)

| Subcommand | Type checking mode |
| -------------- | ------------------ |
| `deno bench` | 📁 Local |
| `deno check` | 📁 Local |
| `deno compile` | 📁 Local |
| `deno eval` | ❌ None |
| `deno repl` | ❌ None |
| `deno run` | ❌ None |
| `deno test` | 📁 Local |

### Permission flags

These are listed [here](/runtime/fundamentals/security/).

### Other runtime flags

More flags which affect the execution environment.

```sh
--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: ...
```
## Key subcommands

| Command | Description |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [`deno run`](/runtime/reference/cli/run/) | Execute a script |
| [`deno serve`](/runtime/reference/cli/serve/) | Run an HTTP server |
| [`deno test`](/runtime/reference/cli/test/) | Run tests |
| [`deno fmt`](/runtime/reference/cli/fmt/) | Format source code |
| [`deno lint`](/runtime/reference/cli/lint/) | Lint source code |
| [`deno check`](/runtime/reference/cli/check/) | Type-check without running |
| [`deno add`](/runtime/reference/cli/add/) | Add a dependency to `deno.json` |
| [`deno install`](/runtime/reference/cli/install/) | Install dependencies |
| [`deno compile`](/runtime/reference/cli/compile/) | Compile to a standalone binary |
| [`deno task`](/runtime/reference/cli/task/) | Run a task defined in `deno.json` |
| [`deno doc`](/runtime/reference/cli/doc/) | Generate documentation |

Each command has its own flags — run `deno <command> --help` for details, or
browse the [CLI reference](/runtime/reference/cli/).
Loading
Loading