Building CLI applications with Deno

When I first encoutered the command line as a green coder, I was intimidated by its stark, text-only interface. Where are my pretty icons and easy drag-and-drop magic? But after a few weeks of hacking away, I learned what the old pros already knew: the CLI offers a level of efficiency and control that graphical interfaces can’t match. Simple wins every time.

You’ve probably used command-line tools countless times in your development career. They’re those handy utilities you run in your terminal that make life easier. But have you considered creating your own? If you’re working with Deno, you’re in luck - building effective CLI applications is surprisingly straightforward once you understand a few key principles.

#Understanding the Command Line Interface

The Command Line Interface (CLI) represents computing in its most direct form—a text-based channel where you communicate with your computer through typed commands rather than visual cues.

Unlike the graphical user interfaces (GUIs) we’ve grown accustomed to, the CLI strips away visual abstractions and connects you directly to the operating system’s core functionality. This direct connection isn’t just about nostalgia or technical purism —it offers tangible benefits that explain why CLIs remain essential tools in modern computing environments.

The advantages become clear once you’ve integrated command line work into your workflow:

• Efficiency: Actions that might require multiple clicks and menu navigations in a GUI can often be accomplished with a single command.
• Precision: The CLI offers granular control over system operations that GUIs sometimes obscure for simplicity.
• Automation potential: Perhaps most powerfully, CLI commands can be chained together in scripts to automate complex or repetitive tasks.

#The anatomy of commands

At their core, commands are simply instructions that tell your computer to perform specific tasks. Think of them as the verbs in the language you’re speaking to your machine. When you type ls to list directory contents or cp to copy files, you’re essentially giving your computer clear, concise directions.

Most commands follow a consistent structure that, once understood, makes learning new commands more intuitive:

command [options/flags] [arguments] 

This structure breaks down into three key components:

1. The command itself: The primary instruction or program you want to execute
2. Options or flags: Modifiers that adjust how the command behaves
3. Arguments: The targets or inputs the command should act upon Consider this example:

ls -l /home/user 

Here, ls is our command (list directory contents), -l is a flag (use long listing format), and /home/user is the argument (the specific directory to examine). This structured approach to command construction creates a consistent pattern across different commands, making the CLI more learnable than it might initially appear.

Flags allow you to customize how commands execute without requiring entirely new commands for each variation.

Flags typically come in two formats:

• Short flags: Single-letter options preceded by a single dash (e.g., -a)
• Long flags: Word-based options preceded by two dashes (e.g., --all)

The beauty of this system is its flexibility. Many commands offer both short and long versions of the same flag, allowing you to choose between brevity and clarity based on your preference or needs.

For efficiency, short flags can often be combined. Instead of typing ls -a -l to see all files in long format, you can simply use ls -al. This shorthand becomes increasingly valuable as you chain more complex commands. Some flags require additional parameters to function properly. For example, when using the grep command to search for text patterns, the -A flag needs a number to specify how many lines of context to display after each match:

grep -A 3 "error" log.txt 

This command would find all instances of “error” in log.txt and display each match plus the three lines that follow it—incredibly useful for understanding the context around error messages.

#Quick intro to Deno

#Running Your First Deno Program

Getting your code up and running in Deno is refreshingly straightforward. Unlike other runtimes that require complex setup procedures, Deno keeps things simple:

1. Create your script file - name it main.ts:

// main.ts
console.log("Hello, Deno!"); 

2. Execute with the run command - Open your terminal and type:

deno run main.ts 

That’s it! Deno automatically handles TypeScript compilation, so there’s no separate build step needed.

One of Deno’s standout features is its security-first approach. By default, your scripts run in a secure sandbox with no access to sensitive system resources. When your code needs additional permissions, you’ll need to grant them explicitly:

deno run --allow-net main.ts # Grants network access
deno run --allow-read main.ts # Grants file reading access
deno run --allow-all main.ts # Grants all permissions (use cautiously!) 

You can even run scripts directly from URLs, which is perfect for quick experiments:

deno run https://deno.land/std/examples/welcome.ts 

#Understanding Output Streams

Your Deno applications have two primary channels for communicating with users: stdout and stderr. Using them correctly makes your programs more powerful and user-friendly.

• Standard Output (stdout) is your main communication channel for results and data:

console.log("Processing complete: 5 files updated"); 

• Standard Error (stderr) is where warnings, errors, and progress messages belong:

console.error("Warning: File permissions denied"); 

This separation might seem like a small detail, but it’s incredibly powerful. When someone pipes your program’s output to another command or file, only the stdout content gets passed along, while error messages still display on screen. For more precise control, Deno provides direct access to these streams:

const encoder = new TextEncoder();
await Deno.stdout.write(encoder.encode("Operation successful!\n"));
await Deno.stderr.write(encoder.encode("Error: Connection timed out\n")); 

#Exit Codes

Exit codes are how your Deno application communicates its success or failure to the system. Think of them as your program’s final statement before closing:

• 0 means success - Everything went as planned
• Non-zero values indicate errors - Different codes can signal different types of failures

Here’s how to set exit codes in your programs:

// When everything succeeds
Deno.exit(0); // Or just let your program finish normally
// When something goes wrong
Deno.exit(1); // General error
Deno.exit(2); // Missing required argument 

Pro tip: Create constants for your different exit codes and document what each means. Your future self (and other developers) will thank you!

const EXIT_CODES = {
  SUCCESS: 0,
  GENERAL_ERROR: 1,
  NETWORK_ERROR: 2,
  FILE_NOT_FOUND: 3
};
// Later in your code
if (!fileExists) {
  console.error("Critical file missing!");
  Deno.exit(EXIT_CODES.FILE_NOT_FOUND);
} 

Exit codes are particularly valuable in automated environments like CI/CD pipelines or when your Deno program is called by other scripts. They allow for programmatic responses to different outcomes without parsing your program’s text output.

#Reading arguments in Deno

At its core, Deno provides a straightforward way to access command-line arguments through the built-in Deno.args array. This read-only array contains all the arguments passed to your script after the filename.

For example, if you run:

deno run main.ts --name=thunky hello world 

Pretty simple, right? The Deno.args array gives you immediate access to everything users type after your script name.

[ "--name=thunky", "hello", "world" ] 

Here is the full example:

// main.ts
/*
Example:
  Command line invocation:
    deno run main.ts --name=thunky hello world

  Expected output:
    [ "--name=thunky", "hello", "world" ]
*/

console.log(Deno.args); 

Here’s a quick and straightforward example of manually parsing Deno.args.

// main.ts
/*
Example:
  Command line invocation:
    deno run main.ts --name=thunky

  Expected output:
    thunky
*/
const args = Deno.args;

const nameArg = args.find(arg => arg.startsWith("--name="));
const name = nameArg ? nameArg.split("=")[1] : "defaultName";

console.log(name); 

While this might seem straightforward initially, manual parsing quickly becomes cumbersome as your CLI tool grows in complexity. Edge cases pile up rapidly—handling optional arguments, default values, error reporting, flags that accept multiple values, and so forth. Deno offers a built-in, powerful, and developer-friendly solution designed specifically to handle these complexities elegantly: parseArgs.

#Deno’s parseArgs function

The parseArgs function (found in @std/cli) transforms those messy command-line inputs into a clean, structured object that your code can easily work with. It handles flags, options, and positional arguments with minimal effort on your part. Translating the output from Deno.args into a simple JavaScript object.

Basic usage

Let’s jump right in with a simple example:

// main.ts
import { parseArgs } from "jsr:@std/cli";

/*
Example:
  Command line invocation:
    deno run main.ts --name=thunky hello world

  Expected output:
    { _: ["hello", "world"], name: "thunky" }
*/

const args = parseArgs(Deno.args);
console.log(args); 

In this example, running the script with deno run main.ts --name=thunky hello world produces the output:

{
  _: ["hello", "world"],
  name: "thunky"
} 

Notice how parseArgs neatly organizes everything with an object containing:

• _: An array of positional arguments (“hello” and “world”).
• Key-value pairs for each option or flag passed (like name: "thunky).
• Flags converted to their specified types (boolean, string, number).

Testing with direct arguments

For testing purposes, you can pass arguments directly to parseArgs, simplifying the process:

import {parseArgs} from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs(["--name=thunky", "hello", "world"]);

assertEquals(args, { _: ["hello", "world"], name: "thunky" }); 

This approach allows you to test argument parsing without executing the entire script from the command line.

Key properties of parseArgs

The parseArgs function offers several options to customize its behavior:

• string option: Specifies argument names that should always be treated as strings, even if they resemble numbers.

import {parseArgs} from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs(["--port=3000"], {
  string: ["port"]
});

assertEquals(args, { _: [], port: "3000" }); 

Without specifying port as a string, parseArgs would interpret 3000 as a number:​

import {parseArgs} from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs(["--port=3000"]);

assertEquals(args, { _: [], port: 3000 }); 

• boolean option: Specifies argument names that should always be treated as booleans. Flags are automatically set to true when present.​

import {parseArgs} from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs(["--verbose"], {
  boolean: ["verbose"]
});


assertEquals(args, { _: [], verbose: true }); 

Without this option, --verbose would require a value like --verbose=true.​

• default option: Provides fallback values when an option isn’t specified.​

import {parseArgs} from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs([], {
  default: { port: 8080 }
});

assertEquals(args, { _: [], port: 8080 }); 

If --port isn’t specified, port defaults to 8080.​

• negatable option: Allows users to negate boolean flags by prefixing them with --no-.

In this example color will return true by default.

import {parseArgs} from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs([], {
  boolean: ["color"],
  default: { color: true }
});


assertEquals(args, { _: [], color: true }); 

Here, --no-color sets color to false:

import {parseArgs} from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs(["--no-color"], {
  boolean: ["color"],
  default: { color: true },
  negatable: ["color"]
});


assertEquals(args, { _: [], color: false }); 

• alias option: Allows defining aliases for arguments, enabling multiple names for the same option. Think of this as nicknames for your options. When your command is long like --help, you can create a shortcut like -h.

import {parseArgs} from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs(["-h"], {
  alias: { h: "help" }
});
assertEquals(args, { _: [], help: true, h: true }) 

import {parseArgs} from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs(["--help"], {
  alias: { h: "help" }
});
assertEquals(args, { _: [], help: true, h: true }) 

Both -h and --help will set help to true.​

• collect option: Need to accept the same flag multiple times? The collect option gathers them into an array:

import {parseArgs} from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs(["--file=a.txt", "--file=b.txt"], {
  collect: ["file"]
});

assertEquals(args, { _: [], file: ["a.txt", "b.txt"] }) 

Without the collect option, only the last value would be kept.​

import {parseArgs} from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs(["--file=a.txt", "--file=b.txt"]);

assertEquals(args, { _: [], file: "b.txt" }) 

• unknown option: The unknownoption lets you control what happens with unexpected flags. Returning false from the unknown handler prevents the unknown option from being added to the result.

import {parseArgs} from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs(["--simplicity"], {
  unknown: (flag) => {
    console.log(`Warning: Unknown flag ${flag}`);
  }
});

assertEquals(args, { _: [], simplicity: true }) 

import {parseArgs} from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs(["--complexity"], {
  unknown: (flag) => {
    console.log(`Warning: Unknown flag ${flag}`);
    return false
  }
});

assertEquals(args, { _: [] }) 

• stopEarly option: When stopEarly is set to true, parsing stops at the first non-option argument. This means anything after that argument won’t be processed as an option, but instead will be placed directly into _.

Imagine you have a CLI tool where the first argument is a command (like “deploy”), and everything after that should be handled by that command rather than being parsed as global options. Without stopEarly, options following the command might be mistakenly interpreted as global options.

Without stopEarly (default behavior): every argument is checked for option syntax regardless of its position:

import { parseArgs } from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";


const args = parseArgs(["--verbose", "deploy", "--force", "--env=production"], {
  boolean: ["verbose"]
});

assertEquals(args, {
  _: ["deploy"],
  verbose: true,
  force: true,
  env: "production"
});
 

Here, even though "deploy" is a command, the parser continues and treats --force and --env=production as global options. This might not be what you want if these options are meant only for the "deploy" command.

With stopEarly: true: the parser stops option processing as soon as it hits the first non-option argument. All subsequent arguments are kept as-is in the positional array (_):

import { parseArgs } from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs(["--verbose", "deploy", "--force", "--env=production"], {
  boolean: ["verbose"],
  stopEarly: true,
});

console.log(args)

assertEquals(args, {_: ["deploy", "--force", "--env=production"], verbose: true }); 

Now the command "deploy" and its related options are not parsed as global flags—they remain in the positional arguments array. This approach is especially useful for CLI applications that support subcommands or delegate the parsing of additional arguments to a different part of your application.

• -- option: The special -- option indicates the end of command options. Everything that comes after -- will be treated as positional arguments (placed in _), even if they look like options.

Without using -- (default behavior):

import {parseArgs} from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs(["--name=thunky", '--ask="How are you?"']);

assertEquals(args, { _: [], name: "thunky", ask: '"How are you?"' }); 

Using -- to explicitly mark the end of options:

import {parseArgs} from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

const args = parseArgs(["--name=thunky", "--", '--ask="How are you?"']);

assertEquals(args, { _: [ '--ask="How are you?"' ], name: "thunky" }); 

This option is handy when you want to pass arguments directly to scripts or commands without the CLI parser confusing them as its own flags.

#Putting it all together

Deno’s parseArgs function gives you a powerful toolkit for handling command-line arguments. By combining these options, you can create intuitive, user-friendly command-line interfaces for your Deno applications.

Whether you’re building a simple script or a complex CLI tool, parseArgs helps you focus on your application logic instead of wrestling with raw command-line inputs.

#Subcommands

import { parseArgs } from "jsr:@std/cli";
import { assertEquals } from "jsr:@std/assert";

function main(args: string[]) {
  const globalOpts = parseArgs(args, { stopEarly: true });
  const [command, ...commandArgs] = globalOpts._;

  if (!command) {
    console.error("No command specified. Available commands: commit, push");
    Deno.exit(1);
  }

  switch (command) {
    case "commit":
      handleCommit(commandArgs);
      break;
    case "push":
      handlePush(commandArgs);
      break;
    default:
      console.error(`Unknown command "${command}". Available commands: commit, push`);
      Deno.exit(1);
  }
}

function handleCommit(args: string[]) {
  const opts = parseArgs(args, {
    string: ["message"],
    alias: { m: "message" },
  });

  if (!opts.message) {
    console.error("Commit message is required (use -m or --message).");
    Deno.exit(1);
  }
  console.log(`Committing changes with message: "${opts.message}"`);
}

function handlePush(args: string[]) {
  const opts = parseArgs(args, {
    boolean: ["force"],
    default: { force: false },
  });
  console.log(`Pushing to remote${opts.force ? " with force" : ""}...`);
}

// Execute main only if the script is run directly.
if (import.meta.main) {
  main(Deno.args);
}