# @magicdawn/x-args

> play with cli commands like a composer

Latest version **3.3.0** (published 2026-09-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @magicdawn/x-args
pnpm add @magicdawn/x-args
yarn add @magicdawn/x-args
bun add @magicdawn/x-args
```

Provides the command `x-args`.

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 3.3.0 |
| Published | 2026-09-01 |
| First published | 2022-06-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 21 |
| Unpacked size | 29.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | magicdawn |
| Maintainers | magicdawn |
| Keywords | x-args, xargs, args-composer, args-manipulator |

## Links

- npm: https://www.npmjs.com/package/@magicdawn/x-args
- Repository: https://github.com/magicdawn/x-args
- Homepage: https://github.com/magicdawn/x-args#readme
- Issues: https://github.com/magicdawn/x-args/issues
- npm.io page: https://npm.io/package/@magicdawn/x-args

## Dependencies (21)

- [ms](https://npm.io/package/ms.md) ^2.1.3
- [zod](https://npm.io/package/zod.md) ^4.5.4
- [obug](https://npm.io/package/obug.md) ^2.1.4
- [boxen](https://npm.io/package/boxen.md) ^8.0.1
- [chalk](https://npm.io/package/chalk.md) ^6.0.0
- [execa](https://npm.io/package/execa.md) ^10.0.1
- [shlex](https://npm.io/package/shlex.md) ^3.0.0
- [p-queue](https://npm.io/package/p-queue.md) ^9.3.3
- [siginfo](https://npm.io/package/siginfo.md) ^2.0.0
- [chokidar](https://npm.io/package/chokidar.md) ^5.0.0
- [emittery](https://npm.io/package/emittery.md) ^2.0.0
- [fs-extra](https://npm.io/package/fs-extra.md) ^11.4.0
- [env-paths](https://npm.io/package/env-paths.md) ^4.0.0
- [fast-glob](https://npm.io/package/fast-glob.md) ^3.3.3
- [superjson](https://npm.io/package/superjson.md) ^2.2.6
- [es-toolkit](https://npm.io/package/es-toolkit.md) ^1.52.0
- [mac-helper](https://npm.io/package/mac-helper.md) ^0.10.0
- [needle-kit](https://npm.io/package/needle-kit.md) ^3.8.0
- [log-symbols](https://npm.io/package/log-symbols.md) ^7.0.1
- [better-result](https://npm.io/package/better-result.md) ^3.0.1
- [proper-lockfile](https://npm.io/package/proper-lockfile.md) ^4.1.2

## Recent versions

- 3.3.0 (latest) — 2026-09-01
- 3.2.1 — 2026-07-09
- 3.2.0 — 2026-07-09
- 3.1.1 — 2026-04-20
- 3.1.0 — 2026-04-20
- 3.0.0 — 2026-04-20
- 2.1.3 — 2026-03-23
- 2.1.2 — 2026-01-25
- 2.1.1 — 2025-12-07
- 2.1.0 — 2025-11-27
- 2.0.1 — 2025-07-01
- 2.0.0 — 2025-06-17
- 1.6.1 — 2025-05-09
- 1.6.0 — 2025-05-09
- 1.5.4 — 2024-07-04
- … 15 more at https://npm.io/package/@magicdawn/x-args/versions

## README

# x-args

> play with cli commands like a composer

[![npm version](https://img.shields.io/npm/v/@magicdawn/x-args.svg?style=flat-square)](https://www.npmjs.com/package/@magicdawn/x-args)
[![npm downloads](https://img.shields.io/npm/dm/@magicdawn/x-args.svg?style=flat-square)](https://www.npmjs.com/package/@magicdawn/x-args)
[![npm license](https://img.shields.io/npm/l/@magicdawn/x-args.svg?style=flat-square)](http://magicdawn.mit-license.org)

## Install

```sh
$ pnpm add @magicdawn/x-args -g

# or
$ pnpm dlx @magicdawn/x-args
$ pnpx @magicdawn/x-args
$ bunx @magicdawn/x-args
```

## Commands

### `x-args` command

```sh
x-args -f './*.*' -c $'cwebp :file -o \':dir/:name_compressed.:ext\''
```

use `-t` to show available tokens

### `txt` sub command

```sh
# use :line
x-args txt ./to-be-processed.txt -c 'echo :line'
```

features that native xargs does not have

- comment, `x-args txt` support `//` or `#` comment, I suggest use `.conf` extenstion, so that editors can recognize `#` comment
- live reload, `x-args txt` read txt file, exec command, and read txt again, so edit after command start will works as well
- wait input update: use `-w,--wait`, so that this command will not exit but to wait txt file update. use `--wait-timeout 1h` to delay `1h` 1 hour.

#### Templates

- use `:line` for whole line
- use `:args0` / `:arg0` for single arg
- use `-s` / `--split` / `--args-split` to specify how to turn `:line` to `:args0`, default using `/\s+/`

when input is a filepath, and may contains space, use a different separator that has low possibility occurs in a filepath
for example

- ancient chinese character for Simplified chinese user: `__纛恚掾旒__`, `--args-split '__纛恚掾旒__'`, [出处](https://mp.weixin.qq.com/s?__biz=MjM5ODI2MTQxOQ==&mid=2653658340&idx=1&sn=32eb7031cdb585eb216ba1490f0629cd&chksm=bd125b208a65d2368daa60d158e9fc12b2997b2324a1d3938727aef3f5f4cecdd7529ea8c6b0&scene=27)
- english user, maybe a emoji combination ?

## Tips

### `-c,--command`

if need single quote in `-c,--command`, u can use `-c $'command \'inside-a-quote\''`, a special shell syntax learn from zx, see

- https://github.com/google/zx/blob/main/docs/quotes.md#quotes
- https://stackoverflow.com/a/16605140

#### `:line` / `:arg0`

this will be auto escaped, no need to manual quote, just use plain `:line` / `:arg0`

### retry

if your `-c,--command` may fail, and u need retry it. u can use https://npm.im/retry-cli

```sh
# install globally
pnpm add -g retry-cli

# add retry to `command-may-fail`
x-args txt ./to-be-processed.txt -c 'retry -- command-may-fail :line'

# retry times 1000, default: 10, see retry-cli homepage
x-args txt ./to-be-processed.txt -c 'retry -n 1000 -- command-may-fail :line'
```

## Changelog

[CHANGELOG.md](CHANGELOG.md)

## License

the MIT License http://magicdawn.mit-license.org

---
_Source: https://npm.io/package/@magicdawn/x-args · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._