주고받는 이메일 데이터에 AI를 활용하는 것에 대한 이야기가 나왔다.

하지만, 이걸 위해 메일 서버를 별도로 구축하거나, 메일 클라이언트와 검색 기능 등을 별도로 코딩하기에는 아무리 AI Code Generation을 쓴다고 해도, 쓸만한 결과물이 나오기까지의 과정이 여간 쉬운 일이 아니다.

결국, 이메일과 관련된 모든 기능이 이미 있는 "MS Office"에 붙어서 바로 코딩할 수 있는 JS 프레임워크를 이용하기로 했다.

MS Outlook의 메일을 AI로 분석하는 실제 예시

// Analyze Microsoft Outlook data with ChatGPT
// Require: WelsonJS framework (https://github.com/gnh1201/welsonjs)
// Workflow: Microsoft Outlook -> OpenAI -> Get Response
var Office = require("lib/msoffice");
var LIE = require("lib/language-inference-engine");

function main(args) {
    var prompt_texts = [];

    var keyword = "example.com";
    var maxCount = 10;
    var previewLen = 160;

    console.log("Searching mails by sender OR recipient contains: '" + keyword + "'.");
    console.log("This test uses Restrict (Sender/To/CC/BCC) + Recipients verification.");
    console.log("Body preview length: " + previewLen);

    var outlook = new Office.Outlook();
    outlook.open();
    outlook.selectFolder(Office.Outlook.Folders.Inbox);

    var results = outlook.searchBySenderOrRecipientContains(keyword);
    console.log("Printing search results. (max " + maxCount + ")");

    results.forEach(function (m, i) {
        var body = String(m.getBody() || "");
        var preview = body.replace(/\r/g, "").replace(/\n+/g, " ").substr(0, previewLen);
        
        var text = "#" + String(i) +
            " | From: " + String(m.getSenderEmailAddress()) +
            " | To: " + String(m.mail.To || "") +
            " | Subject: " + String(m.getSubject()) +
            " | Received: " + String(m.getReceivedTime());

        console.log(text);
        console.log("  Body: " + preview);
        
        // Add an email data to the prompt text context
        prompt_texts.push(text);
        
        // The body to reduce token usage and avoid sending overly large/sensitive content.
        var bodyForPrompt = body;
        var maxBodyLengthForPrompt = 2000; // Keep the body snippet short
        if (bodyForPrompt.length > maxBodyLengthForPrompt) {
            bodyForPrompt = bodyForPrompt.substring(0, maxBodyLengthForPrompt) + "...";
        }
        prompt_texts.push("  Body: " + bodyForPrompt);
    }, maxCount);

    outlook.close();

    // build a AI prompt text
    var instruction_text = "This is an email exchange between the buyer and me, and I would appreciate it if you could help me write the most appropriate reply.";
    prompt_texts.push(instruction_text);

    // complete the prompt text
    var prompt_text_completed = prompt_texts.join("\r\n");

    //console.log(prompt_text_completed);  // print all prompt text

    // get a response from AI
    var response_text = LIE.create().setProvider("openai").inference(prompt_text_completed, 0).join(' ');

    console.log(response_text);
}

exports.main = main;

실행 방법

1. CLI 사용

모든 작성 및 저장을 마친 후, 다음 명령을 통해 실행한다. (outlook_ai.js 파일로 저장했을 때.

cscript app.js outlook_ai

2. GUI 사용

모든 작성 및 저장을 마친 후, WelsonJS Launcher 앱을 통해 실행한다.

실행하면 어떤 결과가 나오는가?

메일 내용에는 개인정보가 포함되어 있으므로 예시는 따로 첨부하지 않았다.

위 코드의 작업이 성공하면 메일 내용이 출력되면서, OpenAI 서버에서 분석을 마친 결과값을 얻어올 수 있다.

Consider Git's -C option:

git -C /path/to/repo checkout <TAB>

When you hit Tab, Git completes branch names from /path/to/repo, not your current directory. The completion is context-aware—it depends on the value of another option.

Most CLI parsers can't do this. They treat each option in isolation, so completion for --branch has no way of knowing the --repo value. You end up with two unpleasant choices: either show completions for all possible branches across all repositories (useless), or give up on completion entirely for these options.

Optique 0.10.0 introduces a dependency system that solves this problem while preserving full type safety.

Static dependencies with or()

Optique already handles certain kinds of dependent options via the or() combinator:

import { flag, object, option, or, string } from "@optique/core";

const outputOptions = or(
  object({
    json: flag("--json"),
    pretty: flag("--pretty"),
  }),
  object({
    csv: flag("--csv"),
    delimiter: option("--delimiter", string()),
  }),
);

TypeScript knows that if json is true, you'll have a pretty field, and if csv is true, you'll have a delimiter field. The parser enforces this at runtime, and shell completion will suggest --pretty only when --json is present.

This works well when the valid combinations are known at definition time. But it can't handle cases where valid values depend on runtime input—like branch names that vary by repository.

Runtime dependencies

Common scenarios include:

• A deployment CLI where --environment affects which services are available
• A database tool where --connection affects which tables can be completed
• A cloud CLI where --project affects which resources are shown

In each case, you can't know the valid values until you know what the user typed for the dependency option. Optique 0.10.0 introduces dependency() and derive() to handle exactly this.

The dependency system

The core idea is simple: mark one option as a dependency source, then create derived parsers that use its value.

import {
  choice,
  dependency,
  message,
  object,
  option,
  string,
} from "@optique/core";

function getRefsFromRepo(repoPath: string): string[] {
  // In real code, this would read from the Git repository
  return ["main", "develop", "feature/login"];
}

// Mark as a dependency source
const repoParser = dependency(string());

// Create a derived parser
const refParser = repoParser.derive({
  metavar: "REF",
  factory: (repoPath) => {
    const refs = getRefsFromRepo(repoPath);
    return choice(refs);
  },
  defaultValue: () => ".",
});

const parser = object({
  repo: option("--repo", repoParser, {
    description: message`Path to the repository`,
  }),
  ref: option("--ref", refParser, {
    description: message`Git reference`,
  }),
});

The factory function is where the dependency gets resolved. It receives the actual value the user provided for --repo and returns a parser that validates against refs from that specific repository.

Under the hood, Optique uses a three-phase parsing strategy:

1. Parse all options in a first pass, collecting dependency values
2. Call factory functions with the collected values to create concrete parsers
3. Re-parse derived options using those dynamically created parsers

This means both validation and completion work correctly—if the user has already typed --repo /some/path, the --ref completion will show refs from that path.

Repository-aware completion with @optique/git

The @optique/git package provides async value parsers that read from Git repositories. Combined with the dependency system, you can build CLIs with repository-aware completion:

import {
  command,
  dependency,
  message,
  object,
  option,
  string,
} from "@optique/core";
import { gitBranch } from "@optique/git";

const repoParser = dependency(string());

const branchParser = repoParser.deriveAsync({
  metavar: "BRANCH",
  factory: (repoPath) => gitBranch({ dir: repoPath }),
  defaultValue: () => ".",
});

const checkout = command(
  "checkout",
  object({
    repo: option("--repo", repoParser, {
      description: message`Path to the repository`,
    }),
    branch: option("--branch", branchParser, {
      description: message`Branch to checkout`,
    }),
  }),
);

Now when you type my-cli checkout --repo /path/to/project --branch <TAB>, the completion will show branches from /path/to/project. The defaultValue of "." means that if --repo isn't specified, it falls back to the current directory.

Multiple dependencies

Sometimes a parser needs values from multiple options. The deriveFrom() function handles this:

import {
  choice,
  dependency,
  deriveFrom,
  message,
  object,
  option,
} from "@optique/core";

function getAvailableServices(env: string, region: string): string[] {
  return [`${env}-api-${region}`, `${env}-web-${region}`];
}

const envParser = dependency(choice(["dev", "staging", "prod"] as const));
const regionParser = dependency(choice(["us-east", "eu-west"] as const));

const serviceParser = deriveFrom({
  dependencies: [envParser, regionParser] as const,
  metavar: "SERVICE",
  factory: (env, region) => {
    const services = getAvailableServices(env, region);
    return choice(services);
  },
  defaultValues: () => ["dev", "us-east"] as const,
});

const parser = object({
  env: option("--env", envParser, {
    description: message`Deployment environment`,
  }),
  region: option("--region", regionParser, {
    description: message`Cloud region`,
  }),
  service: option("--service", serviceParser, {
    description: message`Service to deploy`,
  }),
});

The factory receives values in the same order as the dependency array. If some dependencies aren't provided, Optique uses the defaultValues.

Async support

Real-world dependency resolution often involves I/O—reading from Git repositories, querying APIs, accessing databases. Optique provides async variants for these cases:

import { dependency, string } from "@optique/core";
import { gitBranch } from "@optique/git";

const repoParser = dependency(string());

const branchParser = repoParser.deriveAsync({
  metavar: "BRANCH",
  factory: (repoPath) => gitBranch({ dir: repoPath }),
  defaultValue: () => ".",
});

The @optique/git package uses isomorphic-git under the hood, so gitBranch(), gitTag(), and gitRef() all work in both Node.js and Deno.

There's also deriveSync() for when you need to be explicit about synchronous behavior, and deriveFromAsync() for multiple async dependencies.

Wrapping up

The dependency system lets you build CLIs where options are aware of each other—not just for validation, but for shell completion too. You get type safety throughout: TypeScript knows the relationship between your dependency sources and derived parsers, and invalid combinations are caught at compile time.

This is particularly useful for tools that interact with external systems where the set of valid values isn't known until runtime. Git repositories, cloud providers, databases, container registries—anywhere the completion choices depend on context the user has already provided.

This feature will be available in Optique 0.10.0. To try the pre-release:

deno add jsr:@optique/core@0.10.0-dev.311

Or with npm:

npm install @optique/core@0.10.0-dev.311

See the documentation for more details.

We've all been there. You start a quick TypeScript CLI with process.argv.slice(2), add a couple of options, and before you know it you're drowning in if/else blocks and parseInt calls. It works, until it doesn't.

In this guide, we'll move from manual argument parsing to a fully type-safe CLI with subcommands, mutually exclusive options, and shell completion.

The naïve approach: parsing process.argv

Let's start with the most basic approach. Say we want a greeting program that takes a name and optionally repeats the greeting:

// greet.ts
const args = process.argv.slice(2);

let name: string | undefined;
let count = 1;

for (let i = 0; i < args.length; i++) {
  if (args[i] === "--name" || args[i] === "-n") {
    name = args[++i];
  } else if (args[i] === "--count" || args[i] === "-c") {
    count = parseInt(args[++i], 10);
  }
}

if (!name) {
  console.error("Error: --name is required");
  process.exit(1);
}

for (let i = 0; i < count; i++) {
  console.log(`Hello, ${name}!`);
}

Run node greet.js --name Alice --count 3 and you'll get three greetings.

But this approach is fragile. count could be NaN if someone passes --count foo, and we'd silently proceed. There's no help text. If someone passes --name without a value, we'd read the next option as the name. And the boilerplate grows fast with each new option.

The traditional libraries

You've probably heard of Commander.js and Yargs. They've been around for years and solve the basic problems:

// With Commander.js
import { program } from "commander";

program
  .requiredOption("-n, --name <n>", "Name to greet")
  .option("-c, --count <number>", "Number of times to greet", "1")
  .parse();

const opts = program.opts();

These libraries handle help text, option parsing, and basic validation. But they were designed before TypeScript became mainstream, and the type safety is bolted on rather than built in.

The real problem shows up when you need mutually exclusive options. Say your CLI works either in "server mode" (with --port and --host) or "client mode" (with --url). With these libraries, you end up with a config object where all options are potentially present, and you're left writing runtime checks to ensure the user didn't mix incompatible flags. TypeScript can't help you because the types don't reflect the actual constraints.

Enter Optique

Optique takes a different approach. Instead of configuring options declaratively, you build parsers by composing smaller parsers together. The types flow naturally from this composition, so TypeScript always knows exactly what shape your parsed result will have.

Optique works across JavaScript runtimes: Node.js, Deno, and Bun are all supported. The core parsing logic has no runtime-specific dependencies, so you can even use it in browsers if you need to parse CLI-like arguments in a web context.

Let's rebuild our greeting program:

import { object } from "@optique/core/constructs";
import { option } from "@optique/core/primitives";
import { integer, string } from "@optique/core/valueparser";
import { withDefault } from "@optique/core/modifiers";
import { run } from "@optique/run";

const parser = object({
  name: option("-n", "--name", string()),
  count: withDefault(option("-c", "--count", integer({ min: 1 })), 1),
});

const config = run(parser);
// config is typed as { name: string; count: number }

for (let i = 0; i < config.count; i++) {
  console.log(`Hello, ${config.name}!`);
}

Types are inferred automatically. config.name is string, not string | undefined. config.count is number, guaranteed to be at least 1. Validation is built in: integer({ min: 1 }) rejects non-integers and values below 1 with clear error messages. Help text is generated automatically, and the run() function handles errors and exits with appropriate codes.

Install it with your package manager of choice:

npm add @optique/core @optique/run
# or: pnpm add, yarn add, bun add, deno add jsr:@optique/core jsr:@optique/run

Building up: a file converter

Let's build something more realistic: a file converter that reads from an input file, converts to a specified format, and writes to an output file.

import { object } from "@optique/core/constructs";
import { optional, withDefault } from "@optique/core/modifiers";
import { argument, option } from "@optique/core/primitives";
import { choice, string } from "@optique/core/valueparser";
import { run } from "@optique/run";

const parser = object({
  input: argument(string({ metavar: "INPUT" })),
  output: option("-o", "--output", string({ metavar: "FILE" })),
  format: withDefault(
    option("-f", "--format", choice(["json", "yaml", "toml"])),
    "json"
  ),
  pretty: option("-p", "--pretty"),
  verbose: option("-v", "--verbose"),
});

const config = run(parser, {
  help: "both",
  version: { mode: "both", value: "1.0.0" },
});

// config.input: string
// config.output: string
// config.format: "json" | "yaml" | "toml"
// config.pretty: boolean
// config.verbose: boolean

The type of config.format isn't just string. It's the union "json" | "yaml" | "toml". TypeScript will catch typos like config.format === "josn" at compile time.

The choice() parser is useful for any option with a fixed set of valid values: log levels, output formats, environment names, and so on. You get both runtime validation (invalid values are rejected with helpful error messages) and compile-time checking (TypeScript knows the exact set of possible values).

Mutually exclusive options

Now let's tackle the case that trips up most CLI libraries: mutually exclusive options. Say our tool can either run as a server or connect as a client, but not both:

import { object, or } from "@optique/core/constructs";
import { withDefault } from "@optique/core/modifiers";
import { argument, constant, option } from "@optique/core/primitives";
import { integer, string, url } from "@optique/core/valueparser";
import { run } from "@optique/run";

const parser = or(
  // Server mode
  object({
    mode: constant("server"),
    port: option("-p", "--port", integer({ min: 1, max: 65535 })),
    host: withDefault(option("-h", "--host", string()), "0.0.0.0"),
  }),
  // Client mode
  object({
    mode: constant("client"),
    url: argument(url()),
  }),
);

const config = run(parser);

The or() combinator tries each alternative in order. The first one that successfully parses wins. The constant() parser adds a literal value to the result without consuming any input, which serves as a discriminator.

TypeScript infers a discriminated union:

type Config =
  | { mode: "server"; port: number; host: string }
  | { mode: "client"; url: URL };

Now you can write type-safe code that handles each mode:

if (config.mode === "server") {
  console.log(`Starting server on ${config.host}:${config.port}`);
} else {
  console.log(`Connecting to ${config.url.hostname}`);
}

Try accessing config.url in the server branch. TypeScript won't let you. The compiler knows that when mode is "server", only port and host exist.

This is the key difference from configuration-based libraries. With Commander or Yargs, you'd get a type like { port?: number; host?: string; url?: string } and have to check at runtime which combination of fields is actually present. With Optique, the types match the actual constraints of your CLI.

Subcommands

For larger tools, you'll want subcommands. Optique handles this with the command() parser:

import { object, or } from "@optique/core/constructs";
import { optional } from "@optique/core/modifiers";
import { argument, command, constant, option } from "@optique/core/primitives";
import { string } from "@optique/core/valueparser";
import { run } from "@optique/run";

const parser = or(
  command("add", object({
    action: constant("add"),
    key: argument(string({ metavar: "KEY" })),
    value: argument(string({ metavar: "VALUE" })),
  })),
  command("remove", object({
    action: constant("remove"),
    key: argument(string({ metavar: "KEY" })),
  })),
  command("list", object({
    action: constant("list"),
    pattern: optional(option("-p", "--pattern", string())),
  })),
);

const result = run(parser, { help: "both" });

switch (result.action) {
  case "add":
    console.log(`Adding ${result.key}=${result.value}`);
    break;
  case "remove":
    console.log(`Removing ${result.key}`);
    break;
  case "list":
    console.log(`Listing${result.pattern ? ` (filter: ${result.pattern})` : ""}`);
    break;
}

Each subcommand gets its own help text. Run myapp add --help and you'll see only the options relevant to add. Run myapp --help and you'll see a summary of all available commands.

The pattern here is the same as mutually exclusive options: or() to combine alternatives, constant() to add a discriminator. This consistency is one of Optique's strengths. Once you understand the basic combinators, you can build arbitrarily complex CLI structures by composing them.

Shell completion

Optique has built-in shell completion for Bash, zsh, fish, PowerShell, and Nushell. Enable it by passing completion: "both" to run():

const config = run(parser, {
  help: "both",
  version: { mode: "both", value: "1.0.0" },
  completion: "both",
});

Users can then generate completion scripts:

$ myapp --completion bash >> ~/.bashrc
$ myapp --completion zsh >> ~/.zshrc
$ myapp --completion fish > ~/.config/fish/completions/myapp.fish

The completions are context-aware. They know about your subcommands, option values, and choice() alternatives. Type myapp --format <TAB> and you'll see json, yaml, toml as suggestions. Type myapp a<TAB> and it'll complete to myapp add.

Completion support is often an afterthought in CLI tools, but it makes a real difference in user experience. With Optique, you get it essentially for free.

Integrating with validation libraries

Already using Zod for validation in your project? The @optique/zod package lets you reuse those schemas as CLI value parsers:

import { z } from "zod";
import { zod } from "@optique/zod";
import { option } from "@optique/core/primitives";

const email = option("--email", zod(z.string().email()));
const port = option("--port", zod(z.coerce.number().int().min(1).max(65535)));

Your existing validation logic just works. The Zod error messages are passed through to the user, so you get the same helpful feedback you're used to.

Prefer Valibot? The @optique/valibot package works the same way:

import * as v from "valibot";
import { valibot } from "@optique/valibot";
import { option } from "@optique/core/primitives";

const email = option("--email", valibot(v.pipe(v.string(), v.email())));

Valibot's bundle size is significantly smaller than Zod's (~10KB vs ~52KB), which can matter for CLI tools where startup time is noticeable.

Tips

A few things I've learned building CLIs with Optique:

Start simple. Begin with object() and basic options. Add or() for mutually exclusive groups only when you need them. It's easy to over-engineer CLI parsers.

Use descriptive metavars. Instead of string(), write string({ metavar: "FILE" }) or string({ metavar: "URL" }). The metavar appears in help text and error messages, so it's worth the extra few characters.

Leverage withDefault(). It's better than making options optional and checking for undefined everywhere. Your code becomes cleaner when you can assume values are always present.

Test your parser. Optique's core parsing functions work without process.argv, so you can unit test your parser logic:

import { parse } from "@optique/core/parser";

const result = parse(parser, ["--name", "Alice", "--count", "3"]);
if (result.success) {
  assert.equal(result.value.name, "Alice");
  assert.equal(result.value.count, 3);
}

This is especially valuable for complex parsers with many edge cases.

Going further

We've covered the fundamentals, but Optique has more to offer:

• Async value parsers for validating against external sources, like checking if a Git branch exists or if a URL is reachable
• Path validation with path() for checking file existence, directory structure, and file extensions
• Custom value parsers for domain-specific types (though Zod/Valibot integration is usually easier)
• Reusable option groups with merge() for sharing common options across subcommands
• The @optique/temporal package for parsing dates and times using the Temporal API

Check out the documentation for the full picture. The tutorial walks through the concepts in more depth, and the cookbook has patterns for common scenarios.

That's it

Building CLIs in TypeScript doesn't have to mean fighting with types or writing endless runtime validation. Optique lets you express constraints in a way that TypeScript actually understands, so the compiler catches mistakes before they reach production.

The source is on GitHub, and packages are available on both npm and JSR.

---

Questions or feedback? Find me on the fediverse or open an issue on the GitHub repo.