rubycli 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9809e4d2f9c1ddb0b97f7c7cede2d665888726952e96ed5b14584e9230c617b
-  data.tar.gz: 538af61eb924c66fdd0bf26df5bdcfaba66fbec76daa70ddbfcef943d2cfa654
+  metadata.gz: 14562bc06b2479369c2951a54cac6f8f502e5ff81ae453b25bdb225b2017f671
+  data.tar.gz: 731a6704bac4ca7d9471b4ff00d7476745e81c442666e99ca3b710d70c9e4622
 SHA512:
-  metadata.gz: efc21b5eddfb00f727ae0a056c7507ee36e27cc3da47c7bad0d68f310862f6cb3f7511328ec9bc2ac40f1493fa9b340892482a858623c57ec6ff8a9069ea9f73
-  data.tar.gz: 1f21f11831d6b90b4981034827c33ac9a27a48385fae73cf22e806b7d5728835209f231977c1ca6f609cecd7bdfe12cae30d74adeaf409e0231e616262ced993
+  metadata.gz: 2ef973534a268ac8475f21f9d26ef16202ab5f4a89a69c3ea94a0700f1d89a5b17e533d5e821f8c6833855c91f72a5d5d6fcbfb75716c9a3648bf52e9c26600b
+  data.tar.gz: c2cc78a8dbc2ec9185c6fcb598ea5be2160ea336021932e2ab7ffb58b5b2be5f8fad078ed379a26a33c66241ed69a17c1edd9bd852663299747a630edd9da235

data/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-## [0.1.0] - Unreleased
+## [0.1.2] - 2025-11-06
+
+### Added
+- Example `examples/documentation_style_showcase.rb` covering all supported documentation notations.
+- Parenthesised `(Type)` and `(type: Type)` annotations for positional and option documentation.
+
+### Documentation
+- Linked the showcase example from the English and Japanese READMEs to highlight the new syntax.
+- Clarified that optional arguments do not require brackets in comments and noted the current comma-delimited behaviour for repeated values.
+- Documented the refined literal parsing guard rails so only structured values auto-coerce while plain strings stay untouched unless type hints request otherwise.
+
+### Fixed
+- Restored uppercase positional placeholders in the generated help output so the default style stays consistent.
+- Help renderer now preserves documented placeholder casing instead of wrapping everything in `<...>`.
+- Default literal parsing now skips generic strings to avoid collapsing comma-separated inputs, while still supporting array coercion when documentation specifies list types.
+
+## [0.1.1] - 2025-11-01
 
 ### Added
 - Initial public release of Rubycli with the `rubycli` executable for running documented Ruby classes and modules.

data/README.ja.md

@@ -1,5 +1,7 @@
 # Rubycli — Python Fire 風の Ruby 向け CLI
 
+![Rubycli ロゴ](assets/rubycli-logo.png)
+
 Rubycli は Ruby のクラス／モジュールに書いたコメントから CLI を自動生成する小さなフレームワークです。Python Fire にインスパイアされていますが、互換や公式ポートを目指すものではありません。Ruby のコメント記法と型アノテーションに合わせて設計しています。
 
 > English guide is available in [README.md](README.md).
@@ -28,7 +30,7 @@ Usage: hello_app.rb COMMAND [arguments]
 
 Available commands:
   Class methods:
-    greet                <name>
+    greet                <NAME>
 
 Detailed command help: hello_app.rb COMMAND help
 Enable debug logging: --debug or RUBYCLI_DEBUG=true
@@ -40,10 +42,10 @@ rubycli examples/hello_app.rb greet
 
 ```text
 Error: wrong number of arguments (given 0, expected 1)
-Usage: hello_app.rb greet <NAME>
+Usage: hello_app.rb greet NAME
 
 Positional arguments:
-  NAME
+  NAME    required
 ```
 
 ```bash
@@ -102,7 +104,7 @@ Usage: hello_app_with_docs.rb COMMAND [arguments]
 
 Available commands:
   Class methods:
-    greet                <name> [--shout=<value>]
+    greet                <NAME> [--shout]
 
 Detailed command help: hello_app_with_docs.rb COMMAND help
 Enable debug logging: --debug or RUBYCLI_DEBUG=true
@@ -113,13 +115,13 @@ rubycli examples/hello_app_with_docs.rb greet --help
 ```
 
 ```text
-Usage: hello_app_with_docs.rb greet <NAME> [--shout]
+Usage: hello_app_with_docs.rb greet NAME [--shout]
 
 Positional arguments:
-  NAME  [String] 挨拶対象
+  NAME  [String]  required  挨拶対象
 
 Options:
-  --shout  [Boolean] 大文字で出力 (default: false)
+  --shout  [Boolean]  optional  大文字で出力 (default: false)
 ```
 
 ```bash
@@ -156,7 +158,7 @@ end
 
 - コメントベースで CLI オプションやヘルプを自動生成
 - YARD 形式と `NAME [Type] 説明…` の簡潔記法を同時サポート
-- `--json-args` で渡された引数を自動的に JSON パース
+- 引数はデフォルトで安全なリテラルとして解釈し、必要に応じて厳格 JSON モードや Ruby eval モードを切り替え可能
 - `--pre-script`（エイリアス: `--init`）で任意の Ruby コードを評価し、その結果オブジェクトを公開
 - `RUBYCLI_STRICT=ON` で有効化できる厳格モードにより、コメントとシグネチャの矛盾を警告として検知可能
 
@@ -177,21 +179,17 @@ end
 
 ## インストール
 
-まだ RubyGems で公開していません。リポジトリをクローンしてローカルパスを Bundler に指定するか、`.gemspec` 追加後に `gem build` で `.gem` を作成してインストールしてください。
+Rubycli は RubyGems からインストールできます。
 
 ```bash
-git clone https://github.com/inakaegg/rubycli.git
-cd rubycli
-# gem build rubycli.gemspec
-gem build rubycli.gemspec
-gem install rubycli-<version>.gem
+gem install rubycli
 ```
 
 Bundler 例:
 
 ```ruby
 # Gemfile
-gem "rubycli", path: "path/to/rubycli"
+gem "rubycli"
 ```
 
 ## クイックスタート（Rubycli をスクリプトに組み込む）
@@ -247,22 +245,46 @@ rubycli scripts/multi_runner.rb Admin::Runner list --active
 
 ## コメント記法
 
-| 用途 | YARD 互換 | 簡潔記法 |
-| ---- | --------- | -------- |
-| 位置引数 | `@param name [Type] 説明` | `NAME [Type] 説明`（NAME は大文字） |
-| キーワード引数 | 同上 | `--flag -f FLAG [Type] 説明` |
+| 用途 | YARD 互換 | Rubycli 標準 |
+| ---- | --------- | ----------- |
+| 位置引数 | `@param name [Type] 説明` | `NAME [Type] 説明` |
+| キーワード引数 | 同上 | `--flag -f VALUE [Type] 説明` |
 | 戻り値 | `@return [Type] 説明` | `=> [Type] 説明` |
 
-型は `String` や `Integer` のほか、`String[]` や `Array<String>`, `String | nil` なども利用できます。`[VALUE]` や `[VALUE...]` といったプレースホルダ表現で、真偽値や可変長引数を推論させられます。型名を省略した大文字プレースホルダ（例: `--quiet`）は自動的に Boolean フラグとして扱われます。
+短いオプション（`-f` など）は任意で、登場順も自由です。Rubycli 標準の書き方では次の例が同義になります。
+
+- `--flag -f VALUE [Type] 説明`
+- `--flag VALUE [Type] 説明`
+- `-f --flag VALUE [Type] 説明`
+
+README のサンプルは既定スタイルとして大文字プレースホルダ（`NAME`, `VALUE` など）を使用しています。次項以降の表記揺れは、必要に応じて選べる追加記法です。
+
+### 互換プレースホルダ表記
+
+コメントやヘルプ出力では次の表記も同じ意味として解釈されます。
+
+- 山括弧で値を明示: `--flag <value>`, `NAME [<value>]`
+- ロングオプションの `=` 付き表記: `--flag=<value>`
+- 繰り返し指定: `VALUE...`, `<value>...`
+
+実行時には `--flag VALUE`, `--flag <value>`, `--flag=<value>` のどれで入力しても同じ扱いです。プロジェクトで読みやすいスタイルを選択してください。`[VALUE]` や `[VALUE...]` のような表記を使うと、真偽値・任意値・リストなどの推論が働きます。値プレースホルダを省略したオプション（例: `--quiet`）は自動で Boolean フラグとして扱われます。
+
+> 補足: コメント内で任意引数を角括弧で表す必要はありません。Ruby 側のメソッドシグネチャから必須／任意は自動判定され、ヘルプ出力では Rubycli が適切に角括弧を追加します。
+
+型ヒントは `[String]`, `(String)`, `(type: String)` のように角括弧・丸括弧・`type:` プレフィックスのいずれでも指定できます。複数型は `(String, nil)` や `(type: String, nil)` のように列挙してください。
+
+`VALUE...` のような繰り返し指定（`TAG...` など）や、`[String[]]` / `Array<String>` といった配列型の注釈が付いたオプションは配列として扱われます。JSON/YAML 形式のリスト（例: `--tags '["build","test"]'`）を渡すか、カンマ区切り文字列（`--tags "build,test"`）を渡すことで配列に変換されます。スペース区切りの複数値入力（`--tags build test`）にはまだ対応しておらず、繰り返し注記のないオプションは従来どおりスカラーとして扱われます。
 
 代表的な推論例:
 
-- `ARG1` のように型ラベルを省略した大文字プレースホルダは既定で `String` として扱われます。
-- `--name ARG1` のようにオプションへ大文字プレースホルダだけを指定しても同じく `String` が推論されます。
+- `ARG1` のように型ラベルを省略したプレースホルダは既定で `String` として扱われます。
+- `--name ARG1` のようにオプションへプレースホルダだけを指定しても同じく `String` が推論されます。
 - `--verbose` のように値プレースホルダを省略したオプションは Boolean フラグとして扱われます。
 
 `@example` や `@raise`, `@see`, `@deprecated` などその他の YARD タグは、現状ヘルプ出力には反映されません。
 
+> すべての記法をまとめて試したい場合は `rubycli examples/documentation_style_showcase.rb canonical --help` や `... angled --help` などを実行してみてください。
+
 従来の `@param` 記法も既定で利用できます。簡潔なプレースホルダ記法だけに限定したい場合は `RUBYCLI_ALLOW_PARAM_COMMENT=OFF` を設定してください（厳格モードでの検証は継続されます）。
 
 ### コメントが不足している場合のフォールバック
@@ -293,7 +315,7 @@ Usage: fallback_example.rb COMMAND [arguments]
 
 Available commands:
   Class methods:
-    scale                <amount> [<factor>] [--clamp=<value>] [--notify=<value>]
+    scale                AMOUNT [<FACTOR>] [--clamp=<value>] [--notify]
 
 Detailed command help: fallback_example.rb COMMAND help
 Enable debug logging: --debug or RUBYCLI_DEBUG=true
@@ -304,15 +326,15 @@ rubycli examples/fallback_example.rb scale --help
 ```
 
 ```text
-Usage: fallback_example.rb scale <AMOUNT> [<FACTOR>] [--clamp=<value>] [--notify]
+Usage: fallback_example.rb scale AMOUNT [FACTOR] [--clamp=<CLAMP>] [--notify]
 
 Positional arguments:
-  AMOUNT    [Integer] 処理対象の数値
-  [FACTOR]  (default: 2)
+  AMOUNT  [Integer]  required  処理対象の数値
+  FACTOR             optional  (default: 2)
 
 Options:
-  --clamp CLAMP  (type: String) (default: nil)
-  --notify       (type: Boolean) (default: false)
+  --clamp=<CLAMP>  [String]   optional  (default: nil)
+  --notify         [Boolean]  optional  (default: false)
 ```
 
 `AMOUNT` だけがドキュメント化されていますが、`factor` や `clamp`, `notify` も自動的に補完され、既定値や型が推論されていることがわかります。コメントとシグネチャの矛盾を早期に検知したい場合は `RUBYCLI_STRICT=ON` で厳格モードを有効化してください。
@@ -332,27 +354,27 @@ Options:
 - `@param` の行に続く箇条書きや補足行は CLI の自動生成には使われません。補足情報を表示したい場合は、`--flag ...` 行の説明に含めるか、README など別のドキュメントで扱ってください。
 - `RUBYCLI_ALLOW_PARAM_COMMENT=OFF` にすると `@param`/`@return` などのタグは警告扱いになります。プロジェクト内で簡潔記法へ統一するときはこの環境変数で段階的に移行できます。
 
-## JSON モード
-
-CLI 実行時に `--json-args` を付けると、後続の引数が JSON として解釈され Ruby オブジェクトに変換されます。
+## 引数解析モード
 
-```bash
-rubycli --json-args my_cli.rb MyCLI run '["--config", "{\"foo\":1}"]'
-```
+### 既定のリテラル解析
 
-プログラム側では `Rubycli.with_json_mode(true) { … }` で同じ効果を得られます。
+Rubycli は `{` や `[`、クォート、YAML の先頭記号といった「構造化リテラルらしい」形の引数に対して `Psych.safe_load` を試み、成功すれば Ruby の配列／ハッシュ／真偽値に変換してからメソッドへ渡します。たとえば `--names='["Alice","Bob"]'` や `--config='{foo: 1}'` のような値は追加フラグ無しでネイティブな配列・ハッシュとして届きます。一方、プレーンな `1,2,3` のような文字列はこの段階ではそのまま維持されます（コメントで `String[]` や `TAG...` と宣言されている場合は後段で配列に整形されます）。扱えない形式は自動的に文字列へフォールバックするため、`"2024-01-01"` のような値もそのまま文字列で受け取れますし、構文が崩れていても CLI 全体が落ちることはありません。
 
-## Eval モード
+### JSON モード
 
-`--eval-args` を使うと、後続の引数を Ruby コードとして評価した結果を CLI に渡せます。JSON では表現しづらいオブジェクトを扱いたいときに便利です。
+CLI 実行時に `--json-args`（短縮形 `-j`）を付けると、後続の引数が厳格に JSON として解釈されます。
 
 ```bash
-rubycli --eval-args scripts/data_cli.rb DataCLI run '(1..10).to_a'
+rubycli -j my_cli.rb MyCLI run '["--config", "{\"foo\":1}"]'
 ```
 
-評価は `Object.new.instance_eval { binding }` に対して行われるため、信頼できる環境でのみ利用してください。プログラム側からは `Rubycli.with_eval_mode(true) { … }` で有効化できます。
+YAML 固有の書き方は拒否され、無効な JSON であれば `JSON::ParserError` が発生するため、入力の妥当性を強く保証したいときに便利です。プログラム側では `Rubycli.with_json_mode(true) { … }` で有効化できます。
+
+### Eval モード
+
+`--eval-args`（短縮形 `-e`）を使うと、後続の引数を Ruby コードとして評価した結果を CLI に渡せます。JSON や YAML では表現しづらいオブジェクトを扱いたいときに便利ですが、評価は `Object.new.instance_eval { binding }` 上で行われるため、信頼できる入力に限定してください。コード内では `Rubycli.with_eval_mode(true) { … }` で切り替えられます。
 
-`--eval-args` と `--json-args` は同時指定できません。両方付けた場合はエラーになります。
+`--eval-args`/`-e` と `--json-args`/`-j` は同時指定できません。どちらのモードも既定のリテラル解析を拡張する位置づけなので、用途に応じて厳格な JSON か Ruby eval のどちらかを選択してください。
 
 ## Pre-script ブートストラップ
 

data/README.md

@@ -1,9 +1,13 @@
 # Rubycli — Python Fire-inspired CLI for Ruby
 
+![Rubycli logo](assets/rubycli-logo.png)
+
 Rubycli turns existing Ruby classes and modules into CLIs by reading their documentation comments. It is inspired by [Python Fire](https://github.com/google/python-fire) but is not a drop-in port or an official project; the focus here is Ruby’s documentation conventions and type annotations.
 
 > 🇯🇵 Japanese documentation is available in [README.ja.md](README.ja.md).
 
+![Rubycli demo showing generated commands and invocation](assets/rubycli-demo.gif)
+
 ### 1. Existing Ruby script (Rubycli unaware)
 
 ```ruby
@@ -28,7 +32,7 @@ Usage: hello_app.rb COMMAND [arguments]
 
 Available commands:
   Class methods:
-    greet                <name>
+    greet                <NAME>
 
 Detailed command help: hello_app.rb COMMAND help
 Enable debug logging: --debug or RUBYCLI_DEBUG=true
@@ -40,10 +44,10 @@ rubycli examples/hello_app.rb greet
 
 ```text
 Error: wrong number of arguments (given 0, expected 1)
-Usage: hello_app.rb greet <NAME>
+Usage: hello_app.rb greet NAME
 
 Positional arguments:
-  NAME
+  NAME    required
 ```
 
 ```bash
@@ -102,7 +106,7 @@ Usage: hello_app_with_docs.rb COMMAND [arguments]
 
 Available commands:
   Class methods:
-    greet                <name> [--shout=<value>]
+    greet                <NAME> [--shout]
 
 Detailed command help: hello_app_with_docs.rb COMMAND help
 Enable debug logging: --debug or RUBYCLI_DEBUG=true
@@ -113,13 +117,13 @@ rubycli examples/hello_app_with_docs.rb greet --help
 ```
 
 ```text
-Usage: hello_app_with_docs.rb greet <NAME> [--shout]
+Usage: hello_app_with_docs.rb greet NAME [--shout]
 
 Positional arguments:
-  NAME  [String] Name to greet
+  NAME  [String]  required  Name to greet
 
 Options:
-  --shout  [Boolean] Print in uppercase (default: false)
+  --shout  [Boolean]  optional  Print in uppercase (default: false)
 ```
 
 ```bash
@@ -143,7 +147,12 @@ end
 
 ### 3. (Optional) Embed the runner inside your script
 
-Prefer to launch via `ruby hello_app.rb ...`? Require the gem and delegate to `Rubycli.run` (see Quick start below).
+Prefer to launch via `ruby ...` directly? Require the gem and delegate to `Rubycli.run` (see Quick start below for `examples/hello_app_with_require.rb`).
+
+```bash
+ruby examples/hello_app_with_require.rb greet Hanako --shout
+#=> HELLO, HANAKO!
+```
 
 ## Project Philosophy
 
@@ -156,7 +165,7 @@ Prefer to launch via `ruby hello_app.rb ...`? Require the gem and delegate to `R
 
 - Comment-aware CLI generation with both YARD-style tags and concise placeholders
 - Automatic option signature inference (`NAME [Type] Description…`) without extra DSLs
-- Optional JSON coercion for arguments passed via `--json-args`
+- Safe literal parsing out of the box (arrays / hashes / booleans) with opt-in strict JSON and Ruby eval modes
 - Optional pre-script hook (`--pre-script` / `--init`) to evaluate Ruby and expose the resulting object
 - Opt-in strict mode (`RUBYCLI_STRICT=ON`) that emits warnings whenever comments contradict method signatures
 
@@ -177,29 +186,25 @@ Prefer to launch via `ruby hello_app.rb ...`? Require the gem and delegate to `R
 
 ## Installation
 
-The library is not published on RubyGems yet. Clone the repository and point Bundler to the local path, or build a `.gem` once the `.gemspec` is added.
+Rubycli is published on RubyGems.
 
 ```bash
-git clone https://github.com/inakaegg/rubycli.git
-cd rubycli
-# gem build rubycli.gemspec
-gem build rubycli.gemspec
-gem install rubycli-<version>.gem
+gem install rubycli
 ```
 
 Bundler example:
 
 ```ruby
 # Gemfile
-gem "rubycli", path: "path/to/rubycli"
+gem "rubycli"
 ```
 
 ## Quick start (embed Rubycli in the script)
 
-Step 3 adds `require "rubycli"` so the script can invoke the CLI directly:
+Step 3 adds `require "rubycli"` so the script can invoke the CLI directly (see `examples/hello_app_with_require.rb`):
 
 ```ruby
-# hello_app.rb
+# hello_app_with_require.rb
 require "rubycli"
 
 module HelloApp
@@ -222,10 +227,10 @@ Rubycli.run(HelloApp)
 Run it:
 
 ```bash
-ruby hello_app.rb greet Taro
+ruby examples/hello_app_with_require.rb greet Taro
 #=> Hello, Taro!
 
-ruby hello_app.rb greet Taro --shout
+ruby examples/hello_app_with_require.rb greet Taro --shout
 #=> HELLO, TARO!
 ```
 
@@ -249,22 +254,46 @@ This is useful when a file defines multiple candidates or when you want a nested
 
 Rubycli parses a hybrid format – you can stick to familiar YARD tags or use short forms.
 
-| Purpose | YARD-compatible | Concise form |
-| ------- | --------------- | ------------ |
-| Positional argument | `@param name [Type] Description` | `NAME [Type] Description` (`NAME` must be uppercase) |
-| Keyword option | Same as above | `--flag -f FLAG [Type] Description` |
+| Purpose | YARD-compatible | Rubycli style |
+| ------- | --------------- | ------------- |
+| Positional argument | `@param name [Type] Description` | `NAME [Type] Description` |
+| Keyword option | Same as above | `--flag -f VALUE [Type] Description` |
 | Return value | `@return [Type] Description` | `=> [Type] Description` |
 
-Types accept `String`, `Integer`, `String[]`, `Array<String>`, union `String | nil`, etc. Optional placeholders like `[VALUE]` or `[VALUE...]` let Rubycli infer boolean flags, optional values, and list coercion. When you omit the type on an uppercase placeholder (for example `--quiet`), Rubycli infers a Boolean flag automatically.
+Short options are optional and order-independent, so the following examples are equivalent in Rubycli’s default style:
+
+- `--flag -f VALUE [Type] Description`
+- `--flag VALUE [Type] Description`
+- `-f --flag VALUE [Type] Description`
+
+Our examples keep the classic uppercase placeholders (`NAME`, `VALUE`) as the canonical style; the variations below are optional sugar.
+
+### Alternate placeholder notations
+
+Rubycli also understands these syntaxes when parsing comments and rendering help:
+
+- Angle brackets for user input: `--flag <value>` or `NAME [<value>]`
+- Inline equals for long options: `--flag=<value>`
+- Trailing ellipsis for repeated values: `VALUE...` or `<value>...`
+
+The CLI treats `--flag VALUE`, `--flag <value>`, and `--flag=<value>` identically at runtime—document with whichever variant your team prefers. Optional placeholders like `[VALUE]` or `[VALUE...]` let Rubycli infer boolean flags, optional values, and list coercion. When you omit the placeholder entirely (for example `--quiet`), Rubycli infers a Boolean flag automatically.
+
+> Tip: You do not need to wrap optional arguments in brackets inside the comment. Rubycli already knows which parameters are optional from the Ruby signature and will introduce the brackets in generated help.
+
+You can annotate types using `[String]`, `(String)`, or `(type: String)`—they all convey the same hint, and you can list multiple types such as `(String, nil)` or `(type: String, nil)`.
+
+Repeated values (`VALUE...`) now materialize as arrays automatically whenever the option is documented with an ellipsis (for example `TAG...`) or an explicit array type hint (`[String[]]`, `Array<String>`). Supply either JSON/YAML list syntax (`--tags "[\"build\",\"test\"]"`) or a comma-delimited string (`--tags "build,test"`); Rubycli will coerce both forms to arrays. Space-separated multi-value flags (`--tags build test`) are still not supported, and options without a repeated/array hint continue to be parsed as scalars.
 
 Common inference rules:
 
-- Writing a bare uppercase placeholder such as `ARG1` (without `[String]`) makes Rubycli treat it as a `String`.
+- Writing a placeholder such as `ARG1` (without `[String]`) makes Rubycli treat it as a `String`.
 - Using that placeholder in an option line (`--name ARG1`) also infers a `String`.
 - Omitting the placeholder entirely (`--verbose`) produces a Boolean flag.
 
 Other YARD tags such as `@example`, `@raise`, `@see`, and `@deprecated` are currently ignored by the CLI renderer.
 
+> Want to explore every notation in a single script? Try `rubycli examples/documentation_style_showcase.rb canonical --help`, `... angled --help`, or the other showcase commands.
+
 YARD-style `@param` annotations continue to work out of the box. If you want to enforce the concise placeholder syntax exclusively, set `RUBYCLI_ALLOW_PARAM_COMMENT=OFF` (strict mode still applies either way).
 
 ### When docs are missing or incomplete
@@ -295,7 +324,7 @@ Usage: fallback_example.rb COMMAND [arguments]
 
 Available commands:
   Class methods:
-    scale                <amount> [<factor>] [--clamp=<value>] [--notify=<value>]
+    scale                AMOUNT [<FACTOR>] [--clamp=<value>] [--notify]
 
 Detailed command help: fallback_example.rb COMMAND help
 Enable debug logging: --debug or RUBYCLI_DEBUG=true
@@ -306,15 +335,15 @@ rubycli examples/fallback_example.rb scale --help
 ```
 
 ```text
-Usage: fallback_example.rb scale <AMOUNT> [<FACTOR>] [--clamp=<value>] [--notify]
+Usage: fallback_example.rb scale AMOUNT [FACTOR] [--clamp=<CLAMP>] [--notify]
 
 Positional arguments:
-  AMOUNT    [Integer] Base amount to process
-  [FACTOR]  (default: 2)
+  AMOUNT  [Integer]  required  Base amount to process
+  FACTOR             optional  (default: 2)
 
 Options:
-  --clamp CLAMP  (type: String) (default: nil)
-  --notify       (type: Boolean) (default: false)
+  --clamp=<CLAMP>  [String]   optional  (default: nil)
+  --notify         [Boolean]  optional  (default: false)
 ```
 
 Here only `AMOUNT` is documented, yet `factor`, `clamp`, and `notify` are still presented with sensible defaults and inferred types. Enable strict mode (`RUBYCLI_STRICT=ON`) if you want mismatches between comments and signatures to surface as warnings during development.
@@ -327,27 +356,33 @@ Here only `AMOUNT` is documented, yet `factor`, `clamp`, and `notify` are still
 
 In short, comments never add live parameters by themselves; they enrich or describe what your method already supports.
 
-## JSON mode
+## Argument parsing modes
+
+### Default literal parsing
+
+Rubycli tries to interpret arguments that look like structured literals (values starting with `{`, `[`, quotes, or YAML front matter) using `Psych.safe_load` before handing them to your code. That means values such as `--names='["Alice","Bob"]'` or `--config='{foo: 1}'` arrive as native arrays / hashes without any extra flags. Plain strings like `1,2,3` stay untouched at this stage (if the documentation declares `String[]` or `TAG...`, a later pass still normalises them into arrays), and unsupported constructs fall back to the original text, so `"2024-01-01"` remains a string and malformed payloads still reach your method instead of killing the run.
+
+### JSON mode
 
-Supply `--json-args` when invoking the runner and Rubycli will parse subsequent arguments as JSON before passing them to your method:
+Supply `--json-args` (or the shorthand `-j`) when invoking the runner and Rubycli will parse subsequent arguments strictly as JSON before passing them to your method:
 
 ```bash
-rubycli --json-args my_cli.rb MyCLI run '["--config", "{\"foo\":1}"]'
+rubycli -j my_cli.rb MyCLI run '["--config", "{\"foo\":1}"]'
 ```
 
-Programmatically you can call `Rubycli.with_json_mode(true) { … }`.
+This mode rejects YAML-only syntax and raises `JSON::ParserError` when the payload is invalid, which is handy for callers who want explicit failures instead of silent fallbacks. Programmatically you can call `Rubycli.with_json_mode(true) { … }`.
 
 ## Eval mode
 
-Use `--eval-args` to evaluate Ruby expressions before they are forwarded to your CLI. This is handy when you want to pass rich objects that are awkward to express as JSON:
+Use `--eval-args` (or the shorthand `-e`) to evaluate Ruby expressions before they are forwarded to your CLI. This is handy when you want to pass rich objects that are awkward to express as JSON:
 
 ```bash
-rubycli --eval-args scripts/data_cli.rb DataCLI run '(1..10).to_a'
+rubycli -e scripts/data_cli.rb DataCLI run '(1..10).to_a'
 ```
 
 Under the hood Rubycli evaluates each argument inside an isolated binding (`Object.new.instance_eval { binding }`). Treat this as unsafe input: do not enable it for untrusted callers. The mode can also be toggled programmatically via `Rubycli.with_eval_mode(true) { … }`.
 
-`--eval-args` and `--json-args` are mutually exclusive; Rubycli will raise an error if both are present.
+`--eval-args`/`-e` and `--json-args`/`-j` are mutually exclusive; Rubycli will raise an error if both are present. Both modes augment the default literal parsing, so you can pick either strict JSON or full Ruby evaluation when the defaults are not enough.
 
 ## Pre-script bootstrap
 

data/lib/rubycli/argument_parser.rb

@@ -1,3 +1,4 @@
+require 'psych'
 require_relative 'type_utils'
 
 module Rubycli
@@ -203,11 +204,24 @@ module Rubycli
     end
 
     def convert_arg(arg)
-      return nil if arg.nil? || arg.casecmp('nil').zero?
-      return true if arg.casecmp('true').zero?
-      return false if arg.casecmp('false').zero?
-      return arg.to_i if integer_string?(arg)
-      return arg.to_f if float_string?(arg)
+      return arg if Rubycli.eval_mode? || Rubycli.json_mode?
+      return arg unless arg.is_a?(String)
+
+      trimmed = arg.strip
+      return arg if trimmed.empty?
+
+      if literal_like?(trimmed)
+        literal = try_literal_parse(arg)
+        return literal unless literal.equal?(LITERAL_PARSE_FAILURE)
+      end
+
+      return nil if null_literal?(trimmed)
+
+      lower = trimmed.downcase
+      return true if lower == 'true'
+      return false if lower == 'false'
+      return arg.to_i if integer_string?(trimmed)
+      return arg.to_f if float_string?(trimmed)
 
       arg
     end
@@ -220,6 +234,37 @@ module Rubycli
       str =~ /\A-?\d+\.\d+\z/
     end
 
+    LITERAL_PARSE_FAILURE = Object.new
+
+    def try_literal_parse(value)
+      return LITERAL_PARSE_FAILURE unless value.is_a?(String)
+
+      trimmed = value.strip
+      return value if trimmed.empty?
+
+      literal = Psych.safe_load(trimmed, aliases: false)
+      return literal unless literal.nil? && !null_literal?(trimmed)
+
+      LITERAL_PARSE_FAILURE
+    rescue Psych::SyntaxError, Psych::DisallowedClass, Psych::Exception
+      LITERAL_PARSE_FAILURE
+    end
+
+    def null_literal?(value)
+      return false unless value
+
+      %w[null ~].include?(value.downcase)
+    end
+
+    def literal_like?(value)
+      return false unless value
+      return true if value.start_with?('[', '{', '"', "'")
+      return true if value.start_with?('---')
+      return true if value.match?(/\A(?:true|false|null|nil)\z/i)
+
+      false
+    end
+
 
     def build_cli_alias_map(option_defs)
       option_defs.each_with_object({}) do |opt, memo|
@@ -286,7 +331,7 @@ module Rubycli
       when 'String'
         ->(value) { value }
       when 'Integer', 'Fixnum'
-        ->(value) { Integer(value, 10) }
+        ->(value) { Integer(value) }
       when 'Float'
         ->(value) { Float(value) }
       when 'Numeric'
@@ -324,10 +369,25 @@ module Rubycli
     end
 
     def convert_option_value(keyword, value, option_meta, type_converters)
+      if Rubycli.eval_mode? || Rubycli.json_mode?
+        return convert_arg(value)
+      end
+
       converter = type_converters[keyword]
-      return convert_arg(value) unless converter
+      converted_value = convert_arg(value)
+      return converted_value unless converter
+
+      original_input = value if value.is_a?(String)
+      expects_list = option_meta && option_meta.types.any? { |type|
+        type.to_s.end_with?('[]') || type.to_s.start_with?('Array<')
+      }
+
+      value_for_converter = converted_value
+      if expects_list && original_input && converted_value.is_a?(Numeric) && original_input.include?(',')
+        value_for_converter = original_input
+      end
 
-      converter.call(value)
+      converter.call(value_for_converter)
     rescue StandardError => e
       option_label = option_meta&.long || option_meta&.short || keyword
       raise ArgumentError, "Value '#{value}' for option '#{option_label}' is invalid: #{e.message}"

data/lib/rubycli/command_line.rb

@@ -3,7 +3,7 @@
 module Rubycli
   module CommandLine
     USAGE = <<~USAGE
-      Usage: rubycli [--new|-n] [--pre-script SRC] [--json-args | --eval-args] TARGET_PATH [CLASS_OR_MODULE] [-- CLI_ARGS...]
+      Usage: rubycli [--new|-n] [--pre-script=<src>] [--json-args|-j | --eval-args|-e] <target-path> [<class-or-module>] [-- <cli-args>...]
 
       Examples:
         rubycli scripts/sample_runner.rb echo --message hello
@@ -12,14 +12,16 @@ module Rubycli
 
       Options:
         --new, -n            Instantiate the class/module before invoking CLI commands
-        --pre-script SRC     Evaluate Ruby code and use its result as the exposed target (--init alias)
-        --json-args          Treat all following arguments as JSON
-        --eval-args          Evaluate following arguments as Ruby code
+        --pre-script=<src>   Evaluate Ruby code and use its result as the exposed target (--init alias; also accepts space-separated form)
+        --json-args, -j      Parse all following arguments strictly as JSON (no YAML literals)
+        --eval-args, -e      Evaluate following arguments as Ruby code
         (Note: --json-args and --eval-args are mutually exclusive)
+        (Note: Every option that accepts a value understands both --flag=value and --flag value forms.)
 
-      When CLASS_OR_MODULE is omitted, Rubycli infers it from the file name in CamelCase.
+      When <class-or-module> is omitted, Rubycli infers it from the file name in CamelCase.
+      Arguments are parsed as safe literals by default; pick a mode above if you need strict JSON or Ruby eval.
       Method return values are printed to STDOUT by default.
-      CLI_ARGS are forwarded to Rubycli unchanged.
+      <cli-args> are forwarded to Rubycli unchanged.
     USAGE
 
     module_function
@@ -63,10 +65,10 @@ module Rubycli
           end
           context = File.file?(src) ? File.expand_path(src) : "(inline #{flag})"
           pre_script_sources << { value: src, context: context }
-        when '--json-args'
+        when '--json-args', '-j'
           json_mode = true
           args.shift
-        when '--eval-args'
+        when '--eval-args', '-e'
           eval_mode = true
           args.shift
         when '--print-result'

data/lib/rubycli/documentation_registry.rb

@@ -201,9 +201,27 @@ module Rubycli
         normalized.each do |token|
           token_without_at = token.start_with?('@') ? token[1..] : token
           if token.start_with?('--')
-            long_option = token
+            if (eq_index = token.index('='))
+              long_option = token[0...eq_index]
+              inline_value = token[(eq_index + 1)..]
+              if value_name.nil? && inline_value && !inline_value.strip.empty?
+                value_name = inline_value.strip
+                next
+              end
+            else
+              long_option = token
+            end
           elsif token.start_with?('-')
-            short_option = token
+            if (eq_index = token.index('='))
+              short_option = token[0...eq_index]
+              inline_value = token[(eq_index + 1)..]
+              if value_name.nil? && inline_value && !inline_value.strip.empty?
+                value_name = inline_value.strip
+                next
+              end
+            else
+              short_option = token
+            end
           elsif value_name.nil? && placeholder_token?(token_without_at)
             value_name = token_without_at
           elsif type_token.nil? && type_token_candidate?(token)
@@ -275,16 +293,28 @@ module Rubycli
 
       long_option = nil
       short_option = nil
+      inline_value_from_long = nil
+      inline_value_from_short = nil
       remaining = []
 
       tokens.each do |token|
         if long_option.nil? && token.start_with?('--')
-          long_option = token
+          if (eq_index = token.index('='))
+            long_option = token[0...eq_index]
+            inline_value_from_long = token[(eq_index + 1)..]
+          else
+            long_option = token
+          end
           next
         end
 
         if short_option.nil? && token.start_with?('-') && !token.start_with?('--')
-          short_option = token
+          if (eq_index = token.index('='))
+            short_option = token[0...eq_index]
+            inline_value_from_short = token[(eq_index + 1)..]
+          else
+            short_option = token
+          end
           next
         end
 
@@ -294,7 +324,7 @@ module Rubycli
       return nil unless long_option
 
       type_token = nil
-      value_name = nil
+      value_name = [inline_value_from_long, inline_value_from_short].compact.map(&:strip).find { |val| !val.empty? }
       description_tokens = []
 
       remaining.each do |token|
@@ -335,12 +365,12 @@ module Rubycli
     def parse_positional_line(line)
       return nil if line.start_with?('--') || line.start_with?('-')
 
-      tokens = line.split(/\s+/)
+      tokens = combine_bracketed_tokens(line.split(/\s+/))
       placeholder = tokens.shift
       return nil unless placeholder
 
       clean_placeholder = placeholder.delete('[]')
-      return nil unless clean_placeholder.match?(/\A[A-Z][A-Z0-9_]*\z/)
+      return nil unless placeholder_token?(clean_placeholder)
 
       type_token = nil
       if tokens.first && type_token_candidate?(tokens.first)
@@ -626,6 +656,7 @@ module Rubycli
       BigDecimal
       File
       Pathname
+      nil
     ].freeze
 
     def parse_type_annotation(type_str)
@@ -633,7 +664,9 @@ module Rubycli
 
       cleaned = type_str.strip
       cleaned = cleaned.delete_prefix('@')
+      cleaned = cleaned[1..-2].strip if cleaned.start_with?('(') && cleaned.end_with?(')')
       cleaned = cleaned[1..-2] if cleaned.start_with?('[') && cleaned.end_with?(']')
+      cleaned = cleaned.sub(/\Atype\s*:\s*/i, '')
       cleaned.split(/[,|]/).map { |token| normalize_type_token(token) }.reject(&:empty?)
     end
 
@@ -641,13 +674,29 @@ module Rubycli
       return false unless token
 
       candidate = token.strip.delete_prefix('@')
-      candidate = candidate.delete_prefix('[').delete_suffix(']')
-      candidate = candidate.gsub(/\.\.\./, '')
+      return false if candidate.empty?
+
+      optional = candidate.start_with?('[') && candidate.end_with?(']')
+      candidate = candidate[1..-2].strip if optional
+      return false if candidate.empty?
+
       candidate = candidate.gsub(/[,\|]/, '')
-      candidate = candidate.gsub(/[^A-Za-z0-9_]/, '')
       return false if candidate.empty?
 
-      candidate == candidate.upcase && candidate.match?(/[A-Z]/)
+      ellipsis = candidate.end_with?('...')
+      candidate = candidate[0..-4] if ellipsis
+      candidate = candidate.strip
+      return false if candidate.empty?
+
+      if candidate.start_with?('<') && candidate.end_with?('>')
+        inner = candidate[1..-2]
+        inner.match?(/\A[0-9A-Za-z][0-9A-Za-z._-]*\z/)
+      else
+        cleaned = candidate.gsub(/[^A-Za-z0-9_]/, '')
+        return false if cleaned.empty?
+
+        cleaned == cleaned.upcase && cleaned.match?(/[A-Z]/)
+      end
     end
 
     def type_token_candidate?(token)
@@ -709,6 +758,7 @@ module Rubycli
     def combine_bracketed_tokens(tokens)
       combined = []
       buffer = nil
+      closing = nil
 
       tokens.each do |token|
         next if token.nil?
@@ -716,12 +766,17 @@ module Rubycli
         if buffer
           buffer << ' ' unless token.empty?
           buffer << token
-          if token.include?(']')
+          if closing && token.include?(closing)
             combined << buffer
             buffer = nil
+            closing = nil
           end
         elsif token.start_with?('[') && !token.include?(']')
           buffer = token.dup
+          closing = ']'
+        elsif token.start_with?('(') && !token.include?(')')
+          buffer = token.dup
+          closing = ')'
         else
           combined << token
         end

data/lib/rubycli/help_renderer.rb

@@ -53,21 +53,8 @@ module Rubycli
       summary = metadata[:summary]
       return summary if summary && !summary.empty?
 
-      params = method_obj.parameters
-      return "(no arguments)" if params.empty?
-
-      param_desc = params.map { |type, name|
-        case type
-        when :req then "<#{name}>"
-        when :opt then "[<#{name}>]"
-        when :rest then "[<#{name}>...]"
-        when :keyreq then "--#{name.to_s.tr("_", "-")}=<value>"
-        when :key then "[--#{name.to_s.tr("_", "-")}=<value>]"
-        when :keyrest then "[--<option>...]"
-        end
-      }.compact.join(" ")
-
-      param_desc.empty? ? "(no arguments)" : param_desc
+      params_str = format_method_parameters(method_obj.parameters, metadata)
+      params_str.empty? ? "(no arguments)" : params_str
     end
 
     def usage_for_method(command, method)
@@ -78,59 +65,8 @@ module Rubycli
       options = metadata[:options] || []
       positionals_in_order = ordered_positionals(method, metadata)
 
-      if positionals_in_order.any?
-        labels = positionals_in_order.map { |info| info[:label] }
-        max_label_length = labels.map(&:length).max || 0
-
-        usage_lines << ""
-        usage_lines << "Positional arguments:"
-        positionals_in_order.each do |info|
-          definition = info[:definition]
-          description_parts = []
-          if definition&.inline_type_annotation && definition.inline_type_text
-            description_parts << definition.inline_type_text
-          end
-          type_info = positional_type_display(definition)
-          if type_info && type_info_first?(definition)
-            description_parts << type_info
-          end
-          description_parts << info[:description] if info[:description]
-          description_parts << type_info if type_info && !type_info_first?(definition)
-          default_text = positional_default_display(definition)
-          description_parts << default_text if default_text
-          description_text = description_parts.join(' ')
-          line = "  #{info[:label].ljust(max_label_length)}"
-          line += "  #{description_text}" unless description_text.empty?
-          usage_lines << line
-        end
-      end
-
-      if options.any?
-        option_labels = options.map { |opt| option_flag_with_placeholder(opt) }
-        max_label_length = option_labels.map(&:length).max || 0
-
-        usage_lines << "" unless usage_lines.last == ""
-        usage_lines << "Options:"
-        options.each_with_index do |opt, idx|
-          label = option_labels[idx]
-          description_parts = []
-          if opt.inline_type_annotation && opt.inline_type_text
-            description_parts << opt.inline_type_text
-          end
-          type_info = option_type_display(opt)
-          if type_info && type_info_first?(opt)
-            description_parts << type_info
-          end
-          description_parts << opt.description if opt.description
-          description_parts << type_info if type_info && !type_info_first?(opt)
-          default_info = option_default_display(opt)
-          description_parts << default_info if default_info
-          description_text = description_parts.join(' ')
-          line = "  #{label.ljust(max_label_length)}"
-          line += "  #{description_text}" unless description_text.empty?
-          usage_lines << line
-        end
-      end
+      usage_lines.concat(render_positionals(positionals_in_order)) if positionals_in_order.any?
+      usage_lines.concat(render_options(options, required_keyword_names(method))) if options.any?
 
       returns = metadata[:returns] || []
       if returns.any?
@@ -168,14 +104,11 @@ module Rubycli
       parameters.map { |type, name|
         case type
         when :req
-          doc = positional_map[name]
-          label = doc&.label || name.to_s.upcase
-          "<#{label}>"
+          positional_usage_token(type, name, positional_map[name])
         when :opt
-          doc = positional_map[name]
-          label = doc&.label || name.to_s.upcase
-          "[<#{label}>]"
-        when :rest then "[<#{name}>...]"
+          positional_usage_token(type, name, positional_map[name])
+        when :rest
+          positional_usage_token(type, name, positional_map[name])
         when :keyreq
           opt = option_map[name]
           if opt
@@ -202,53 +135,163 @@ module Rubycli
         when :keyrest then "[--<option>...]"
         else ""
         end
-      }.reject(&:empty?).join(" ")
+      }.compact.reject(&:empty?).join(" ")
     end
 
     def auto_generated_option_usage_label(name, opt)
       base_flag = "--#{name.to_s.tr('_', '-')}"
       return base_flag if opt.boolean_flag
 
-      "#{base_flag}=<value>"
+      value_name = opt.value_name
+      formatted = if value_name && !value_name.to_s.strip.empty?
+                    ensure_angle_bracket_placeholder(value_name)
+                  else
+                    "<value>"
+                  end
+      "#{base_flag}=#{formatted}"
+    end
+
+    def render_positionals(positionals_in_order)
+      rows = positionals_in_order.map do |info|
+        definition = info[:definition]
+        label = info[:label]
+        type = formatted_types(definition&.types)
+        requirement = positional_requirement(info[:kind])
+        description_parts = []
+        description_parts << info[:description] if info[:description]
+        default_text = positional_default(definition)
+        description_parts << default_text if default_text
+        [label, type, requirement, description_parts.join(' ')]
+      end
+      table_block("Positional arguments:", rows)
+    end
+
+    def render_options(options, required_keywords)
+      rows = options.map do |opt|
+        label = option_flag_with_placeholder(opt)
+        type = formatted_types(opt.types)
+        requirement = required_keywords.include?(opt.keyword) ? 'required' : 'optional'
+        description_parts = []
+        description_parts << opt.description if opt.description
+        default_text = option_default(opt)
+        description_parts << default_text if default_text
+        [label, type, requirement, description_parts.join(' ').strip]
+      end
+      table_block("Options:", rows)
+    end
+
+    def table_block(header, rows)
+      return [] if rows.empty?
+
+      cols = rows.transpose
+      widths = cols.map { |col| col.map { |value| value.to_s.length }.max || 0 }
+
+      lines = ["", header]
+      rows.each do |row|
+        padded = row.each_with_index.map do |value, idx|
+          text = value.to_s
+          idx < row.length - 1 ? text.ljust(widths[idx]) : text
+        end
+        lines << "  #{padded.join('  ')}".rstrip
+      end
+      lines
+    end
+
+    def formatted_types(types)
+      type_list = Array(types).compact.map(&:to_s).reject(&:empty?).uniq
+      return '' if type_list.empty?
+
+      "[#{type_list.join(', ')}]"
+    end
+
+    def positional_requirement(kind)
+      kind == :opt ? 'optional' : 'required'
+    end
+
+    def positional_default(definition)
+      return nil unless definition
+      value = definition.default_value
+      return nil if value.nil? || value.to_s.empty?
+
+      "(default: #{value})"
     end
 
+ def option_default(opt)
+   value = opt.default_value
+   return nil if value.nil? || value.to_s.empty?
+
+   "(default: #{value})"
+ end
+
+ def required_keyword_names(method)
+   method.parameters.select { |type, _| type == :keyreq }.map { |_, name| name }
+ end
+
     def ordered_positionals(method, metadata)
       positional_map = metadata[:positionals_map] || {}
       method.parameters.each_with_object([]) do |(type, name), memo|
         next unless %i[req opt].include?(type)
 
         definition = positional_map[name]
-        label = if definition
-            type == :opt ? "[#{definition.label}]" : definition.label
-          else
-            base = name.to_s.upcase
-            type == :opt ? "[#{base}]" : base
-          end
+        label = display_label_for(definition, name)
         description = definition&.description
-        memo << { label: label, description: description, definition: definition }
+        memo << { label: label, description: description, definition: definition, kind: type }
       end
     end
 
-    def positional_type_display(definition)
-      return nil unless definition
-      return nil if definition.inline_type_annotation
-      return nil if definition.types.nil? || definition.types.empty?
+    def display_label_for(definition, name)
+      return definition.label if definition&.label && !definition.label.to_s.empty?
 
-      unique_types = definition.types.reject(&:empty?).uniq
-      return nil if unique_types.empty?
+      name.to_s.upcase
+    end
 
-      if definition.respond_to?(:doc_format) && definition.doc_format == :rubycli
-        "[#{unique_types.join(', ')}]"
+    def positional_usage_token(type, name, definition)
+      placeholder = extract_positional_placeholder(definition)
+      case type
+      when :req
+        required_placeholder(placeholder, definition, name)
+      when :opt
+        optional_placeholder(placeholder, definition, name)
+      when :rest
+        rest_placeholder(placeholder, definition, name)
       else
-        "(type: #{unique_types.join(' | ')})"
+        nil
       end
     end
 
-    def positional_default_display(definition)
-      return nil unless definition && definition.default_value
-      return nil if definition.default_value.to_s.empty?
+    def extract_positional_placeholder(definition)
+      return nil unless definition
+      return nil if definition.doc_format.nil?
+
+      token = definition.placeholder.to_s.strip
+      token.empty? ? nil : token
+    end
+
+    def required_placeholder(placeholder, definition, name)
+      return placeholder.strip unless placeholder.nil? || placeholder.strip.empty?
+
+      default_positional_label(definition, name, uppercase: true)
+    end
+
+    def optional_placeholder(placeholder, definition, name)
+      return placeholder.strip unless placeholder.nil? || placeholder.strip.empty?
+
+      "[#{default_positional_label(definition, name, uppercase: true)}]"
+    end
+
+    def rest_placeholder(placeholder, definition, name)
+      return placeholder.strip unless placeholder.nil? || placeholder.strip.empty?
 
-      "(default: #{definition.default_value})"
+      base = default_positional_label(definition, name, uppercase: true)
+      "[#{base}...]"
+    end
+
+    def default_positional_label(definition, name, uppercase:)
+      label = definition&.label
+      label = label.to_s.strip unless label.nil?
+      label = nil if label.respond_to?(:empty?) && label.empty?
+      base = label || name.to_s
+      uppercase ? base.upcase : base
     end
 
     def option_flag_with_placeholder(opt)
@@ -257,7 +300,13 @@ module Rubycli
       flag_label = flags.join(", ")
       placeholder = option_value_placeholder(opt)
       if placeholder
-        "#{flag_label} #{placeholder}"
+        formatted = ensure_angle_bracket_placeholder(placeholder)
+        if formatted.start_with?('[') && formatted.end_with?(']')
+          inner = formatted[1..-2]
+          "#{flag_label}[=#{inner}]"
+        else
+          "#{flag_label}=#{formatted}"
+        end
       else
         flag_label
       end
@@ -271,28 +320,25 @@ module Rubycli
       first_non_nil_type
     end
 
-    def option_type_display(opt)
-      return nil if opt.inline_type_annotation
-      return nil if opt.types.nil? || opt.types.empty?
-
-      unique_types = opt.types.reject(&:empty?).uniq
-      return nil if unique_types.empty?
+    def ensure_angle_bracket_placeholder(placeholder)
+      raw = placeholder.to_s.strip
+      return raw if raw.empty?
 
-      if opt.respond_to?(:doc_format) && opt.doc_format == :rubycli
-        "[#{unique_types.join(', ')}]"
-      else
-        "(type: #{unique_types.join(' | ')})"
-      end
-    end
+      optional = raw.start_with?('[') && raw.end_with?(']')
+      core = optional ? raw[1..-2].strip : raw
+      return raw if core.empty?
 
-    def option_default_display(opt)
-      return nil if opt.default_value.nil? || opt.default_value.to_s.empty?
+      ellipsis = core.end_with?('...')
+      core = core[0..-4] if ellipsis
 
-      "(default: #{opt.default_value})"
-    end
+      formatted_core = if core.start_with?('<') && core.end_with?('>')
+                         core
+                       else
+                         "<#{core}>"
+                       end
 
-    def type_info_first?(definition)
-      definition.respond_to?(:doc_format) && definition.doc_format == :rubycli
+      formatted_core = "#{formatted_core}..." if ellipsis
+      optional ? "[#{formatted_core}]" : formatted_core
     end
   end
 end

data/lib/rubycli/type_utils.rb

@@ -19,6 +19,10 @@ module Rubycli
       trimmed = trimmed.delete_prefix('@')
       return '' if trimmed.empty?
 
+      trimmed = trimmed[1..-2].strip if trimmed.start_with?('(') && trimmed.end_with?(')')
+      trimmed = trimmed.sub(/\Atype\s*:\s*/i, '').strip
+      return '' if trimmed.empty?
+
       if trimmed.include?('<') && trimmed.end_with?('>')
         trimmed
       elsif trimmed.end_with?('[]')
@@ -66,7 +70,29 @@ module Rubycli
         working.unshift('Boolean') unless working.any? { |type| boolean_type?(type) }
       end
 
-      working.uniq
+      if placeholder_info[:list]
+        array_type_present = false
+
+        working = working.map do |type|
+          next type if type.nil? || type.empty?
+
+          if boolean_type?(type) || nil_type?(type)
+            type
+          elsif type.end_with?('[]') || type.start_with?('Array<') || type.casecmp('Array').zero?
+            array_type_present = true
+            type
+          else
+            array_type_present = true
+            "#{type}[]"
+          end
+        end
+
+        unless array_type_present
+          working << 'String[]'
+        end
+      end
+
+      working.compact.uniq
     end
 
     def determine_requires_value(value_placeholder:, types:, boolean_flag:, optional_value:)
@@ -101,6 +127,7 @@ module Rubycli
 
     def parse_list(value)
       return [] if value.nil?
+      return value if value.is_a?(Array)
 
       value.to_s.split(',').map(&:strip).reject(&:empty?)
     end

data/lib/rubycli/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rubycli
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rubycli
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - inakaegg
 bindir: exe
 cert_chain: []
-date: 2025-11-01 00:00:00.000000000 Z
+date: 2025-11-06 00:00:00.000000000 Z
 dependencies: []
 description: Rubycli turns plain Ruby classes and modules into command-line interfaces
   by reading their documentation comments, inspired by Python Fire but tailored for
@@ -61,5 +61,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.2
 specification_version: 4
-summary: Doc-comment driven CLI wrapper for Ruby classes and modules.
+summary: Python Fire-inspired doc-comment CLI wrapper delivering a Ruby Fire experience.
 test_files: []