For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /cli/alias/placeholders.md.
  • English
  • Placeholders

    Placeholder Namespaces

    The three namespaces are fully isolated:

    NamespaceSyntaxDescription
    Named placeholders{xxx}Matches the value that directly follows xxx in the input
    Optional pass-through{{xxx}}Rendered as-is when xxx is present; disappears otherwise
    System placeholders${...}Fixed semantics provided by the system
    Variables (expanded first)

    ${byk_dir} / ${file_dir} / ${deps_dir} and any $var-declared variables are substituted with literals by byk before placeholder resolution. They are not part of the argument namespaces above — they consume no argument positions and accept no input values. ${args} / ${N} / ${...args} are still handled by the argument layer. See Variables.

    Placeholder Reference

    PlaceholderDescriptionPositions consumed
    {xxx}Matches the value directly following xxx in the input2 (xxx + value)
    {{xxx}}Optional pass-through; renders as xxx value when present, disappears otherwise2 (when present)
    {xxx?}Conditional rendering (simplest); renders as xxx when present, disappears otherwise1
    {xxx?render1:render2}Conditional rendering (ternary)1
    ${N}The Nth raw argument (0-based)1 (position N)
    ${args}All raw argumentsNone
    ${...args}Remaining arguments (excluding those already consumed by other placeholders)None

    Consumption Rules

    • {xxx} / {{xxx}} consume xxx and the value directly following it (2 positions in total)
    • {xxx?} / {xxx?render1} / {xxx?render1:render2} consume only xxx itself (1 position)
    • ${N} consumes position N
    • A placeholder that appears multiple times is consumed only once; its value is reused
    • The remainder for ${...args} = all raw arguments − already-consumed positions, joined in original order

    Missing Values / No Placeholders

    No placeholders

    When an alias contains no placeholders, all raw arguments are appended automatically — equivalent to an implicit ${args} at the end. Bare {} in commands like find (e.g. find . -exec ... {} +) stays compatible: it is never parsed or substituted.

    Missing values

    When a placeholder finds no corresponding value, it silently disappears — no error is raised. Errors caused by missing arguments are handled at runtime by the underlying command.

    Argument Fidelity

    The command is ultimately interpreted by sh -c, so every argument is single-quoted when it is spliced in — the quotes hold the boundary instead of letting the shell re-split it:

    You typeThe command receives
    byk probe "my file.json"one argument my file.json
    byk probe ""one argument (empty)
    byk probe 'a; echo INJECTED'one argument a; echo INJECTED; echo never runs
    byk probe "*.json"one argument *.json, no globbing
    byk probe 'C:\tmp\x'one argument C:\tmp\x, backslash intact

    Only plain values (letters, digits and - _ . / : = @ + ,) go in bare, so the hint line still reads cp src dst; you see quotes only when they are needed: cp 'my file.json' dst.

    Arguments are not expanded again

    *, ~ and $VAR were already handled by your own shell before byk saw them — the * in byk probe *.json has been expanded to a file list by then. Passing them through literally is fidelity, not loss.

    Windows

    The cmd side uses double quotes. The one known gap is %VAR%: cmd expands environment variables even inside quotes, and there is no reliable escape at the command line (%% only works inside batch files).

    Named Placeholder Examples

    Long options
    Short options
    # "copy": "cp {--src} {--dest}"
    byk copy --src foo.txt --dest bar.txt
    # runs: cp foo.txt bar.txt

    Optional Pass-Through Examples

    # "build": "vite build {{--mode}}"
    byk build --mode production
    # runs: vite build --mode production
    
    byk build
    # runs: vite build

    Conditional Rendering Examples

    Simplest form
    Ternary form
    # "dev": "vite {--open?--open}"
    byk dev --open
    # runs: vite --open
    
    byk dev
    # runs: vite

    Positional Argument Examples

    Absolute position
    Repeated use
    Remaining arguments
    # "echo": "echo ${0} ${2}"
    byk echo aaa bbb ccc
    # runs: echo aaa ccc