deno-cli-tool

Deno CLI Tool

Rules for building single-file CLI tools with Deno. For general scripting rules (imports, built-in API preference, prohibited technologies), see script-rules.

Core Principles

1. Single file — one .ts file unless explicitly told otherwise
2. Executable via shebang — include permissions in shebang, install with chmod +x
3. No build step — Deno runs TypeScript directly

Tech Stack

Argument Parsing (REQUIRED: Effect CLI)

Always use Effect CLI for argument parsing:

Purpose	Package	Registry
CLI framework	@effect/cli	jsr:@totto2727/[email protected]/effect/cli
Core / Schema	effect	jsr:@totto2727/[email protected]/effect
HTTP client	@effect/platform	jsr:@totto2727/[email protected]/effect/platform
Node runtime	@effect/platform-node	jsr:@totto2727/[email protected]/effect/platform/node

Other Libraries

Purpose	Package	Registry
Terminal spinner	ora	npm:ora
Terminal colors	ansis	npm:ansis
YAML parsing	@std/yaml	jsr:@std/yaml
Path utilities	@std/path	jsr:@std/path

Shebang

Only request the minimum permissions needed:

#!/usr/bin/env -S deno run --allow-read --allow-write --allow-net

Common flags: --allow-read, --allow-write, --allow-net, --allow-env, --allow-run, --allow-ffi

Setup

chmod +x my-tool.ts

Effect CLI Basic Pattern

A minimal Effect CLI tool with a single command:

#!/usr/bin/env -S deno run --allow-read
import { Console, Effect } from 'jsr:@totto2727/[email protected]/effect'
import { Args, Command } from 'jsr:@totto2727/[email protected]/effect/cli'
import { NodeContext, NodeRuntime } from 'jsr:@totto2727/[email protected]/effect/platform/node'
import * as process from 'node:process'

const name = Args.text({ name: 'name' })

const main = Command.make('greet', { name }, ({ name }) => Console.log(`Hello, ${name}!`))

const cli = Command.run(main, { name: 'greet', version: '0.1.0' })

cli(process.argv).pipe(Effect.provide(NodeContext.layer), NodeRuntime.runMain)

Template

• templates/effect.ts — Effect CLI with subcommands, HTTP client, schema validation

Reference

• references/c7.ts — production example (Context7 CLI client using Effect)