From a87b5db66ede4621d94adaf687cb24a0b1f0353e Mon Sep 17 00:00:00 2001
From: Yang Jun <harttleharttle@gmail.com>
Date: Mon, 27 Jul 2026 21:38:17 +0800
Subject: [PATCH] feat: accept CLI template as positional or --template

Support positional <template> alongside --template/-t for compatibility; error if both are set and differ. Bare stdin template remains removed; @- still works.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 README.md                      |  3 ++-
 bin/liquid.js                  | 18 +++++++++++++++---
 docs/source/tutorials/setup.md | 19 ++++++++++---------
 3 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index d3f638c5f..16affc679 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,8 @@ npm install liquidjs
 **CLI**
 
 ```bash
-npx liquidjs --template 'Hello, {{ name }}!' --context '{"name": "Liquid"}'
+npx liquidjs 'Hello, {{ name }}!' --context '{"name": "Liquid"}'
+# or: npx liquidjs --template 'Hello, {{ name }}!' --context '{"name": "Liquid"}'
 ```
 
 See the [setup guide][setup] for partials, layouts, caching, and other options.
diff --git a/bin/liquid.js b/bin/liquid.js
index 703f4a99f..964f8515b 100755
--- a/bin/liquid.js
+++ b/bin/liquid.js
@@ -14,7 +14,8 @@ async function render () {
   program
     .name('liquidjs')
     .description('Render a Liquid template')
-    .requiredOption('-t, --template <liquid | @path>', 'liquid template to render (inline, @path, or @- for stdin)')
+    .argument('[template]', 'liquid template to render (inline, @path, or @- for stdin)')
+    .option('-t, --template <liquid | @path>', 'liquid template to render (inline, @path, or @- for stdin)')
     .option('-c, --context <json | @path>', 'input context in JSON format (inline, @path, or @- for stdin)')
     .option('-o, --output <path>', 'write rendered output to file (omit to write to stdout)')
     .option('--cache [size]', 'cache previously parsed template structures (default cache size: 1024)')
@@ -45,12 +46,23 @@ async function render () {
     .parse()
 
   const options = program.opts()
+  const positionalTemplate = program.args[0]
+  const optionTemplate = options.template
 
-  if (Object.values(options).filter((value) => value === '@-').length > 1) {
+  if (positionalTemplate && optionTemplate && positionalTemplate !== optionTemplate) {
+    throw new Error(`Conflicting templates: positional argument and --template differ.`)
+  }
+
+  const templateOption = positionalTemplate || optionTemplate
+  if (!templateOption) {
+    throw new Error(`A template is required. Pass a positional <template> or --template.`)
+  }
+
+  if (Object.values({ template: templateOption, context: options.context }).filter((value) => value === '@-').length > 1) {
     throw new Error(`The stdin input specifier '@-' must only be used once.`)
   }
 
-  const template = await resolveInputOption(options.template)
+  const template = await resolveInputOption(templateOption)
   const context = await resolveContext(options.context)
   const liquid = new Liquid(options)
   const output = liquid.parseAndRenderSync(template, context)
diff --git a/docs/source/tutorials/setup.md b/docs/source/tutorials/setup.md
index 3bafc6522..f0799126f 100644
--- a/docs/source/tutorials/setup.md
+++ b/docs/source/tutorials/setup.md
@@ -53,39 +53,40 @@ Pre-built UMD bundles are also available:
 
 ## LiquidJS in CLI
 
-LiquidJS can also be used to render a template directly from CLI using `npx`:
+LiquidJS can also be used to render a template directly from CLI using `npx`. Pass the template as a positional argument, or with `--template` / `-t`:
 
 ```bash
+npx liquidjs '{{"hello" | capitalize}}'
 npx liquidjs --template '{{"hello" | capitalize}}'
 ```
 
 You can either pass the template inline (as shown above), read it from a file with `@` followed by a path, or from `stdin` with `@-`:
 
 ```bash
-npx liquidjs --template @./some-template.liquid
-echo '{{"hello" | capitalize}}' | npx liquidjs --template @-
+npx liquidjs @./some-template.liquid
+echo '{{"hello" | capitalize}}' | npx liquidjs @-
 ```
 
 A context can be passed the same ways (inline, from a path, or via `@-` for `stdin`). The following three are equivalent:
 
 ```bash
-npx liquidjs --template 'Hello, {{ name }}!' --context '{"name": "Snake"}'
-npx liquidjs --template 'Hello, {{ name }}!' --context @./some-context.json
-echo '{"name": "Snake"}' | npx liquidjs --template 'Hello, {{ name }}!' --context @-
+npx liquidjs 'Hello, {{ name }}!' --context '{"name": "Snake"}'
+npx liquidjs 'Hello, {{ name }}!' --context @./some-context.json
+echo '{"name": "Snake"}' | npx liquidjs 'Hello, {{ name }}!' --context @-
 ```
 
-Note that you can only use the `stdin` specifier `@-` for a single argument. If you try to use it for both `--template` and `--context` you will get an error.
+Note that you can only use the `stdin` specifier `@-` for a single argument. If you try to use it for both the template and `--context` you will get an error.
 
 The rendered output is written to `stdout` by default, but you can also specify an output file (if the file exists, it will be overwritten):
 
 ```bash
-npx liquidjs --template '{{"hello" | capitalize}}' --output ./hello.txt
+npx liquidjs '{{"hello" | capitalize}}' --output ./hello.txt
 ```
 
 You can also pass a number of options to customize template rendering behavior. For example, the `--js-truthy` option can be used to enable JavaScript truthiness:
 
 ```bash
-npx liquidjs --template @./some-template.liquid --js-truthy
+npx liquidjs @./some-template.liquid --js-truthy
 ```
 
 Most of the [options available through the JavaScript API][options] are also available from the CLI. For help on available options, use `npx liquidjs --help`.