What is Hackers' Pub?

Hackers' Pub is a place for software engineers to share their knowledge and experience with each other. It's also an ActivityPub-enabled social network, so you can follow your favorite hackers in the fediverse and get their latest posts in your feed.

0
0
0
0
0
1

When building CLI tools, shell completion usually treats each option in isolation. But sometimes valid values for one option depend on another—like branch names depending on which repository you're targeting. Wrote about how I solved this in Optique, a type-safe CLI parser for TypeScript.

Your CLI's completion should k...

Your CLI's completion should know what options you've already typed

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 yourcurrent directory. The completion is context-aware—it depends on the value ofanother option. Most CLI parsers can't do this. They treat each option in isolation, socompletion for --branch has no way of knowing the --repo value. You end upwith two unpleasant choices: either show completions for all possiblebranches across all repositories (useless), or give up on completion entirelyfor these options. Optique 0.10.0 introduces a dependency system that solves this problem whilepreserving 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 ifcsv is true, you'll have a delimiter field. The parser enforces this atruntime, and shell completion will suggest --pretty only when --json ispresent. This works well when the valid combinations are known at definition time. Butit can't handle cases where valid values depend on runtime input—likebranch 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 usertyped for the dependency option. Optique 0.10.0 introduces dependency() andderive() to handle exactly this. The dependency system The core idea is simple: mark one option as a dependency source, then createderived 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 sourceconst repoParser = dependency(string());// Create a derived parserconst 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 theactual value the user provided for --repo and returns a parser that validatesagainst refs from that specific repository. Under the hood, Optique uses a three-phase parsing strategy: Parse all options in a first pass, collecting dependency values Call factory functions with the collected values to create concrete parsers Re-parse derived options using those dynamically created parsers This means both validation and completion work correctly—if the user hasalready typed --repo /some/path, the --ref completion will show refs fromthat path. Repository-aware completion with @optique/git The @optique/git package provides async value parsers that read from Gitrepositories. Combined with the dependency system, you can build CLIs withrepository-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>, thecompletion will show branches from /path/to/project. The defaultValue of"." means that if --repo isn't specified, it falls back to the currentdirectory. 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. Ifsome dependencies aren't provided, Optique uses the defaultValues. Async support Real-world dependency resolution often involves I/O—reading from Gitrepositories, querying APIs, accessing databases. Optique provides asyncvariants 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, sogitBranch(), gitTag(), and gitRef() all work in both Node.js and Deno. There's also deriveSync() for when you need to be explicit about synchronousbehavior, and deriveFromAsync() for multiple async dependencies. Wrapping up The dependency system lets you build CLIs where options are aware of eachother—not just for validation, but for shell completion too. You get typesafety throughout: TypeScript knows the relationship between your dependencysources and derived parsers, and invalid combinations are caught at compiletime. This is particularly useful for tools that interact with external systems wherethe set of valid values isn't known until runtime. Git repositories, cloudproviders, databases, container registries—anywhere the completion choicesdepend 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.

hackers.pub · Hackers' Pub

Link author: 洪 民憙 (Hong Minhee)@hongminhee@hackers.pub

0

When building CLI tools, shell completion usually treats each option in isolation. But sometimes valid values for one option depend on another—like branch names depending on which repository you're targeting.

Wrote about how I solved this in Optique, a type-safe CLI parser for TypeScript.

https://hackers.pub/@hongminhee/2026/optique-context-aware-cli-completion

1
0
0
0

① CJK 환경에서 리눅스의 사용편의성이 윈도에 비견될만한가?
 아니요, 아직 멀었음. 이건 전제로 두고 이야기를 시작함.
② 리눅스 시스템 관리에 CLI가 필수이거나 UAC가 켜져있는 윈도보다 더 크게 불편한 점이 있는가?
 전혀 아니요, 10년도 더 전에 리눅스 써보고 그 경험이 아직도 유효하다고 생각하시면 안 됨. 요즘 전부 GUI로 클릭 두세 번에 다 해결되고, 윈도랑 크게 차이도 안 남.
③ 리눅스 한국어 입력기에 근본적인 사용성 문제가 있는가?
 아니요, OOTB로 작동하지 않는 것 이외에, IBus나 Fcitx에 근본적인 사용성 문제가 있다는 생각은 한 번도 해본 적 없음.

0
0
0
0
0
0

Quand j'ai chaud
Je bois de l'eau
Quand j'ai peur
Je cherche mon cœur
Quand j'ai mal
Ça passe, normal
Quand je n'ai rien
Je lève mon poing
Contre les riches
Et ceux qui s'en fichent

0

① CJK 환경에서 리눅스의 사용편의성이 윈도에 비견될만한가?
 아니요, 아직 멀었음. 이건 전제로 두고 이야기를 시작함.
② 리눅스 시스템 관리에 CLI가 필수이거나 UAC가 켜져있는 윈도보다 더 크게 불편한 점이 있는가?
 전혀 아니요, 10년도 더 전에 리눅스 써보고 그 경험이 아직도 유효하다고 생각하시면 안 됨. 요즘 전부 GUI로 클릭 두세 번에 다 해결되고, 윈도랑 크게 차이도 안 남.
③ 리눅스 한국어 입력기에 근본적인 사용성 문제가 있는가?
 아니요, OOTB로 작동하지 않는 것 이외에, IBus나 Fcitx에 근본적인 사용성 문제가 있다는 생각은 한 번도 해본 적 없음.

0
0
0
0
0
0
0
1
0
0
0
0
1
0

Quand j'ai chaud
Je bois de l'eau
Quand j'ai peur
Je cherche mon cœur
Quand j'ai mal
Ça passe, normal
Quand je n'ai rien
Je lève mon poing
Contre les riches
Et ceux qui s'en fichent

0

日本の海底からレアアース採取で「もう日本は大丈夫!中国何するものぞ」と湧いてる連中を指して"いま飢饉なのに柿の苗を植えて「8年後に柿食えるからもう大丈夫!」と言ってるようなもん"みたいに指摘してた人がいたが、教育に関してもそんなもん。

0
0
0
0

ゲーム『クソネミキングダム』はソフトオフトゥンから発売されたRPGゲームシリーズ。クソネミキングダムシリーズとしては3シリーズ発売され、累計販売本数は334万本であった。

0
0
1
1
0
0
1
0
0
0
1
0
0
0

洪 民憙 (Hong Minhee) :nonbinary: shared the below article:

Your CLI's completion should know what options you've already typed

洪 民憙 (Hong Minhee) @hongminhee@hackers.pub

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.

Read more →
5
0
1
0

jnkrtech replied to the below article:

Your CLI's completion should know what options you've already typed

洪 民憙 (Hong Minhee) @hongminhee@hackers.pub

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.

Read more →
5
1