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/config.md.
  • English
  • Alias Configuration

    Type Definitions

    alias.types.ts
    // Alias object (the metadata-carrying form)
    type AliasObject = {
      $cmd?: string;
      $cwd?: string;
      $mode?: 'normal' | 'interactive' | 'silent';
      $description?: string;
      $recursive?: boolean;
      $private?: boolean;
      $clone?: boolean;
      [key: string]: string | AliasObject | boolean | undefined;
    }
    
    // File-level dependency declaration: assets, pip packages, npm packages
    type Deps = {
      base?: string;
      files?: Array<string | { src: string; to?: string; name?: string; extract?: boolean; exec?: boolean }>;
      pip?: string[];
      npm?: string[];
    };
    
    // A single *.byk.json file: an alias object, or a one-entry link array
    type AliasFileJSON =
      | {
          $priority?: number;      // ordering priority; defaults to 1 in the current directory, 0 globally; negatives become 0
          $cwd?: string;           // file- or group-level working directory, inherited by child aliases
          $mode?: 'normal' | 'interactive' | 'silent';  // file- or group-level mode, inherited by child aliases
          $private?: boolean;      // file- or group-level visibility, inherited by child aliases; private aliases stay out of the merged space
          $clone?: boolean;        // file- or group-level copy tag, inherited by child aliases; false keeps a subtree out of ..clone copies
          $paths?: string[];       // file-level PATH directories, inherited by child aliases
          $deps?: Deps;            // file-level dependencies: assets, pip packages, npm packages
          $var?: Record<string, string | Record<string, string>>;  // file-level variables
          [key: string]: string | AliasObject | Deps | number | boolean | undefined;
        }
      | [string];  // single link: an array holding exactly one path

    Only these eight $-prefixed keys are interpreted at file level; any other $xxx is never treated as an alias and never joins the merged space — it is kept for other tools to store configuration. A ${xxx} inside a string is handled by variables, and undeclared names are passed to the shell verbatim.

    Alias Objects

    Key Naming Rules

    • A key cannot contain @ or .; violating entries are silently ignored
    • Chinese key names are supported
    • Nested groups (objects) are supported and accessed with the . separator
    chinese-keys.byk.json
    {
      "开发": {
        "测试": "pytest -q",
        "构建": "pnpm run build"
      }
    }
    byk 开发.测试

    System Fields

    FieldTypeDescription
    $cmdstringThe command to execute
    $cwdstringWorking directory (inheritable)
    $mode'normal' | 'interactive' | 'silent'How to run the alias (inheritable), defaults to normal
    $descriptionstringHelp-page description text (not inheritable)
    $recursivebooleanAllow re-entering this alias on the call chain (not inheritable), defaults to false — see Recursion Guard
    $privatebooleanKeep this subtree out of the merged space, reachable only through exact calls (inheritable), defaults to false — see Visibility
    $clonebooleanKeep this subtree out of ..clone copies (inheritable), defaults to true — see Cloning
    Note

    An object containing $cmd is an alias leaf node. An object with only $cwd / $mode / $private / $clone but no $cmd is a group with inherited properties and is not executable itself.

    Working Directory (cwd)

    Three levels of inheritance: file → group → alias, with the level closer to the alias winning. ~ expands, and a relative path is resolved against the alias file's directory — not the directory you happened to run byk from. With no $cwd at all, the alias runs in the invocation directory.

    Alias level
    Group level
    File level
    {
      "install": {
        "$cmd": "npm i",
        "$cwd": "/project/web"
      }
    }

    A file-level $cwd is inherited by every child alias. If one alias needs to return to the directory where you typed byk, set its $cwd to "${work_dir}":

    {
      "$cwd": "/project/web",
      "here": { "$cmd": "pwd", "$cwd": "${work_dir}" }
    }

    ${work_dir} is substituted during the scan phase as an absolute path, so writing it is equivalent to writing that absolute path directly and it no longer takes part in relative-path resolution. It is the directory in which the current byk process started: when alias A calls byk B from its own $cwd, B sees A's working directory as ${work_dir}.

    Execution Mode

    $mode decides how an alias runs. The three states are mutually exclusive and normal is the default.

    ValueBehavior
    normalPrint the hint lines, then run directly
    interactivePrint the hint lines, ask for each placeholder, then wait for Enter
    silentSay nothing even on a terminal (a pipe already gets nothing)

    Before running, byk prints two lines to stderr: the source (file.key plus the working directory) and the resolved command. They belong there because they are commentary for a human, not data to be piped:

    • byk build > log.txt and byk build | grep error receive only the command's own output;
    • when stderr is not a terminal (redirected with 2>, CI, editor tasks) the two lines are skipped entirely;
    • $mode: "silent" is for staying quiet on a terminal as well.
    byk build
    # > @.build /project
    #
    # > pnpm build
    #
    # ...(output of pnpm)
    
    # with "$mode": "silent"
    byk build
    # ...(output of pnpm only)

    interactive fits commands with side effects:

    byk deploy
    # ~ deploy --env {env} --tag {version}
    #   env: staging
    #   version: v2.0
    # ~ deploy --env staging --tag v2.0     ← bold green
    #    Press Enter to execute...

    $mode inherits through three levels — file, group, alias — with the closest one winning.

    Alias level
    Group level
    File level
    {
      "deploy": {
        "$cmd": "deploy --env {env} --tag {version}",
        "$mode": "interactive"
      }
    }
    Note

    Interactive and silent are the two extremes of one axis: interactive has to show what is about to run, so silent merely keeps byk quiet — it never skips a confirmation step. Reach for interactive when a command needs one.

    Recursion Guard

    $cmd is an arbitrary shell string, so it can invoke byk again — including resolving back to itself. Give the add alias a $cmd of byk add and every level re-expands the same alias; each level is its own process, so there is no stack to overflow, only a process count that keeps climbing until the machine gives up.

    byk therefore leaves a trail on the call chain: before running an alias it pushes file.key onto the BYK_ALIAS_STACK environment variable (comma-separated) and hands it to the child process. A level that finds itself already on the chain reports and exits:

    Error: alias recursion detected: @dev.build -> @dev.release -> @dev.build

    The whole chain is printed, not just the endpoints — which level looped back is the thing worth locating. Chains deeper than 32 levels are stopped as well: that backstop exists for wrappers that scrub the environment (env -i byk build), where the trail cannot survive and depth is all that is left.

    Deliberate self-invocation (FOO=1 byk build, sudo byk serve) needs an explicit opt-in; these two are equivalent:

    {
      "build": {
        "$cmd": "FOO=1 byk build",
        "$recursive": true
      }
    }
    BYK_ALLOW_RECURSION=1 byk build   # temporary, global

    Opting in only disables the "same alias re-entered" check; the depth limit still applies.

    Note

    $recursive applies to the current alias only and is not inherited. $mode: "silent" does not suppress this error either — explaining why a command hung is exactly what it is for.

    Description Text

    $description replaces the command text shown by default in the help page. It applies to the current alias only and is not inherited.

    {
      "release": {
        "$mode": "interactive",
        "$cmd": "cz bump {version}",
        "$description": "Bump the version interactively"
      }
    }
    byk -h excerpt
    Aliases:
      release    Bump the version interactively

    When unset, the command itself is shown:

    Aliases:
      release    cz bump {version}

    A resolved $cwd is appended in parentheses only when no description is set — with a description, the line stays a single summary and the working directory is left out.

    PATH Directories

    $paths prepends directories to PATH before an alias runs, letting the alias call executables in those directories directly.

    File level only — all child aliases inherit it; writing it inside a group is ignored.

    run.byk.json
    {
      "$paths": ["./scripts", "~/tools/bin"],
      "deploy": "deploy.sh",
      "check": "lint.sh"
    }
    • Relative paths are resolved against the directory containing the config file, and ~ expands
    • Nonexistent directories are silently skipped — they never reach the child process's PATH
    • Separately, byk always prepends the working directory's node_modules/.bin; when the file declares $deps.pip / $deps.npm, the dependency directory's venv bin / node_modules/.bin is prepended as well — no need to write either into $paths yourself
    • The order of $paths is the order in PATH, so earlier entries win

    Dependencies

    $deps declares what an alias file needs — asset files plus optional pip and npm packages — and byk installs them into that file's dedicated directory:

    FileDedicated directory
    Global ~/.byk/alias/hello.byk.json~/.byk/deps/@@hello/
    Local ./hello.byk.json./.byk/deps/@hello/

    Both scopes follow the same rules, only the root differs: global dependencies stay under ~/.byk, local ones travel with the project (delete the project, delete its dependencies — no global clutter). A local install writes .byk/deps/.gitignore containing *, so downloaded assets never show up in git status.

    The declaration itself never touches the network — installing is an explicit verb:

    byk @@tool..deps install      # fetch files and install declared packages
    byk @@tool..deps status       # declared, present, missing, stale
    byk @@tool..deps uninstall    # delete the whole dedicated directory
    byk @@tool..clone <source> -d # or install them right after cloning
    ~/.byk/alias/tool.byk.json
    {
      "$deps": {
        "base": "https://example.com/releases/v1/",
        "files": [
          "tool-1.4.tar.gz",
          { "src": "cli-linux", "to": "bin", "exec": true },
          { "src": "../shared/config.json", "name": "tool.cfg", "to": "etc" },
          "https://cdn.example.com/elsewhere.bin"
        ],
        "pip": ["requests", "click>=8.0"],
        "npm": ["chalk", "@scope/pkg@^1.2"]
      },
      "$paths": ["${deps_dir}/bin"],
      "run": { "$cmd": "tool --version" }
    }
    RuleDescription
    String shorthandEquals { "src": "..." }; the file name is derived from the last segment of the address
    baseThe resolution base for relative src, as a directory. On disk it must be absolute: a remote clone writes an absolute http(s) URL, a local clone writes a local absolute path. You normally do not write this by hand — ..clone records it for you. A hand-written value must be a literal: an absolute URL, an absolute path, or a relative form that ..clone will interpret (., ../, sub/dir). Variables are not supported
    srcAn absolute http(s) URL, or a path relative to base (./x, ../x, bin/tool); variables are expanded before validation, so a value like ${url} is fine. Absolute addresses are fetched with the system curl, local paths are copied directly, and a missing curl errors with an install hint
    toA subdirectory relative to the dedicated directory (root by default); / separated only, .., absolute paths and backslashes rejected
    nameThe saved file name, overriding the derived value; mutually exclusive with extract
    extractExtract as a tar-family archive (tar.gz / tar.xz / tar.bz2, compression auto-detected), delegated to the system tar; to is the target directory and the log marks the line with (extract). Without to the archive unpacks into the dependency root, which requires it to be the only entry (reinstalling replaces the whole directory). Archive entries escaping the target directory abort the install. Mutually exclusive with exec
    execMarks the downloaded file executable (no-op on Windows)
    pipPython package specs (PEP 508, e.g. requests, click>=8.0); installed into .venv inside the dedicated directory, created with python3 (python on Windows) when missing. The venv's bin / Scripts is prepended to PATH. Requires Python 3
    npmnpm package specs (chalk, commander@^12, @scope/pkg); installed into the dedicated directory's node_modules with a minimal package.json (byk-deps, private). node_modules/.bin is prepended to PATH. Requires Node.js / npm
    Sync (files)The declaration is the desired state: missing assets are added, changed ones replaced, removed ones deleted; the manifest in .byk-deps.json means unchanged assets are never re-downloaded
    Scoped removalOnly paths recorded in the manifest and no longer declared are deleted; anything else is left in place with a warning
    Confirmationinstall no longer asks twice: it prints each file / pip / npm action, then runs; uninstall still confirms
    Linkage..rename renames the dedicated directory along, ..destroy deletes it, ..link warns about a stale directory when retargeting

    Packages install alongside file entries. $deps.pip and $deps.npm run on every ..deps install — pip and npm decide what is current — so --force only affects file entries. Neither is recorded in .byk-deps.json: removing a spec from the declaration does not uninstall it; ..deps uninstall clears the whole directory instead. ..deps status lists each package as pip:<spec> / npm:<spec>; a pip direct reference (URL or VCS) is unknown because there is no package name to check locally. files is optional, so a declaration may contain only packages.

    base is the only field clone rewrites. A landed alias file lives in ~/.byk/alias/ and carries no location of its own, so relative paths can only be interpreted at clone time. The form it is frozen into depends on where the bytes came from, and that form decides how assets are fetched:

    Clone sourcebase landed on diskHow assets are fetched
    Remote (URL, -gh / -ge / -jd)Absolute http(s) directory URLcurl
    Local (@@name, @name, a path)Local absolute directory pathdirect copy

    Neither side crosses into the other: a remote clone only ever writes the URL form, so an alias file you got from the network cannot read local files. That is not enforced by a check — the local-path form simply never reaches it.

    The fill-in rules are the same for both, only the base point and the product differ: absent means the source file's directory, a relative form (., ../, sub/dir) is resolved against the source file, and an absolute address (URL or path) is kept as-is with only the trailing / added. The base point is always the source file's directory, never the destination directory — the relative paths in files were written against the source document, and those files are not sitting next to ~/.byk/alias/.

    Writing base back makes clone re-serialise the document (keys sorted). Files with neither $deps nor $clone are untouched and stay byte-for-byte copies; when base already holds the value about to be written, nothing is rewritten either, so cloning twice produces no diff. Cloning rejects variables in base. A clone has no variable table, so "base": "${CDN}" cannot be evaluated; guessing a value would bake a bogus address into the file, so clone fails and tells you to fix the source. (Reading is laxer: ..deps i expands variables first, so a hand-written ${CDN} that resolves to an absolute address still works. The restriction is about clone, and the editor schema follows the clone side.) base is meant to be a literal written by a program: clone freezes it once, and every later reader sees the same thing.

    A local base is not portable: it names an absolute path on this machine and means nothing on another. Local dependencies are meant to be local development aids — do not expect a shared alias file to keep working.

    On Windows there is one more rule: a /sub-style base has no drive letter, so Windows resolves it against the current drive and the same file points somewhere else after a cd. Only relative paths and drive-letter absolutes (C:/share/) are accepted; /sub fails with an error.

    Local entries are compared by the source file's mtime: a source newer than the installed copy triggers a reinstall, so editing a local build artefact and rerunning ..deps i takes effect (use --force for an unconditional rebuild). URL entries have no such notion — the same address is the same content, so keep is always safe. A missing source file is reported with its path instead of a quiet "up to date".

    Reference the dedicated directory with ${deps_dir}. byk owns that directory: installing syncs file entries to the declaration, so do not keep anything there that must survive an install.

    --check only validates the declaration itself (does it parse, do two entries collide, does a relative src have a base, are package entries non-empty strings); what is missing or outdated is ..deps status's job.

    $var, $paths and $deps itself all go through variable substitution first, so custom variables like ${version} can build URLs.

    A local file that wants dependencies: first create a global link with ..init --link. The declaration travels with the target file, while the install location follows the link file's key. See Single Link.

    Variables

    Variables come from two places and are merged into a single table, substituted once during the scan phase:

    SourceDescription
    Built-in${byk_dir} → ~/.byk (the resource root, not the binary directory); ${work_dir} → the directory byk was invoked from (unaffected by $cwd); ${file_dir} → the directory holding the current alias file; ${deps_dir} → that file's dependency directory: ~/.byk/deps/@@<file-name> for global files, <file-dir>/.byk/deps/@<file-name> for local ones
    $var declarationsFile-scoped custom variables

    On a name collision, the file declaration wins — the value you wrote explicitly is the value you get.

    The syntax is uniformly ${name}, where name matches [A-Za-z_][A-Za-z0-9_]* (the same rule as shell identifiers):

    run.byk.json
    {
      "$var": {
        "BASE": "https://github.com/owner/repo/releases/download",
        "VER": {
          "darwin-arm64": "tool-mac",
          "linux-x86_64": "tool-linux"
        }
      },
      "fetch": "curl -fsSL ${BASE}/${VER} -o /tmp/tool",
      "log": "tail -f ${byk_dir}/logs/app.log"
    }
    RuleDescription
    Syntax${name} — the braces are the delimiter and are required
    Bare $xxNot recognized; passed to the shell as-is ($HOME, $PATH are still expanded by the shell)
    ScopeFile-level: applies to all string values including $cmd / $cwd / $paths; JSON keys are untouched
    ResultEvery built-in expands to an absolute path, equivalent to writing that absolute path directly in the config; ${work_dir} can therefore go straight into $cwd to override an inherited value
    OverrideA $var entry with a built-in's name takes that built-in's place
    Self-referenceIn "byk_dir": "${byk_dir}/tools" the right-hand side is the built-in value, yielding ~/.byk/tools
    Escaping\${byk_dir} is passed to the shell untouched, printing the literal ${byk_dir}
    Platform mappingA value can be a platform map (linux-x86_64 / linux-arm64 / darwin-x86_64 / darwin-arm64 / windows-x64); the current platform's value is used
    Cross-referencesValues may reference each other regardless of declaration order, for at most 8 rounds
    Undefined${XXX} is kept as-is; args is reserved for placeholders and its declaration is ignored
    Invalid namesNames that are not valid identifiers are ignored with a warning on stderr
    Why the braces are mandatory

    A bare $byk_dir has no terminator: there is no way to tell whether $byk_dirfoo means the variable byk_dirfoo or byk_dir followed by foo. ${byk_dir}foo has no such ambiguity — which is also why it matches the shell syntax you already know.

    Quoting is your job: when a value contains whitespace, wrap it in quotes per shell rules; byk will not do it for you.

    run.byk.json
    {
      "log": "tail -f \"${byk_dir}/my logs/app.log\"",
      "where": "echo ${file_dir}"
    }

    Keep the three directories apart:

    VariablePoints at
    ${file_dir}The directory holding the alias file
    ${work_dir}The directory byk was invoked from, unaffected by any $cwd inheritance
    $cwd / $PWDThe directory the command actually runs in

    Do not use the shell's $PWD to find the invocation directory: byk starts the shell with $cwd as its working directory, so $PWD is reset to $cwd and can never see the invocation directory. Windows' %CD% behaves the same way. Use ${work_dir} instead.

    Usage Examples

    System fields
    Nested groups
    {
      "dev": "vite",
    
      "install": {
        "$cmd": "npm i",
        "$cwd": "/Users/me/project/web"
      },
    
      "deploy": {
        "$cmd": "deploy --env {env}",
        "$mode": "interactive"
      }
    }
    byk install          # runs npm i in /Users/me/project/web

    Alias Files

    byk reads two locations: the global directory ~/.byk/alias/ and the current working directory (non-recursive).

    File Naming

    FormatExampleDescription
    [name].byk.jsonrun.byk.jsonRecommended form; the name is the file key
    .byk.json.byk.jsonAnonymous form; the key is an empty string
    Warning

    Legal characters: letters, digits, -, _, and Chinese characters.

    Forbidden characters: ., @, /, and spaces.

    Illegally named files (such as aaa.bbb.byk.json) are silently skipped — no error is raised.

    Directory Layout

    # global
    ~/.byk/alias
    alias.byk.json
    work.byk.json
    .byk.json
    # current directory
    .
    run.byk.json
    release.byk.json
    .byk.json

    When the root is an array holding one path, the file is a link file: a pointer to another alias file:

    ~/.byk/alias/ops.byk.json
    ["~/proj/web/run.byk.json"]

    The link file gives up its own identity: the @ / @@ prefix, its key and its default priority stay with the link file, while the aliases and every declaration come from the target — and relative paths resolve against the target's directory. The same bundle therefore behaves identically whether it is scanned directly or reached through a link.

    ~/proj/web/run.byk.json
    {
      "$cwd": ".",
      "build": "node build.js",
      "deploy": "node deploy.js"
    }
    byk build           # runs node build.js inside ~/proj/web
    byk @@ops.build     # exact call goes through the link's key
    RuleBehavior
    One entry onlyExtra entries are ignored with a note on stderr; the first is used
    Path baseRelative paths resolve against the link file's directory; ~ and ${...} work
    One levelThe target may not itself be an array; that is an error and the file is skipped
    IdentityKey, @ / @@ prefix and default priority come from the link; everything else from the target
    $privateStill honoured: a target with true pulls the link out of the merged namespace, leaving exact calls only
    Dependencies$deps declared in the target works as usual; the install location follows the link file's key: ~/.byk/deps/@@<link-file-name> for a global link, <link-dir>/.byk/deps/@<link-file-name> for a local one
    Note

    A missing target, broken JSON or an empty array only skips that one file — other aliases keep working.

    Priority

    All merged files share a single key space, and higher-priority files override lower-priority ones.

    Defaults

    File locationDefault priority
    Current directory [name].byk.json1
    Current directory .byk.json1 (loads last among its peers)
    Global [name].byk.json0
    Global .byk.json0 (loads last among its peers)

    Hence "near-first": project files automatically override same-named global aliases, so byk <key> works the moment you enter a directory — no declaration needed.

    Files at the same priority load in alphabetical order by filename, and the anonymous .byk.json sorts last among its peers; later files override earlier ones. So if both a.byk.json and .byk.json in one directory define build, the .byk.json copy is the one that runs.

    Running inside the global directory

    When the cwd happens to be ~/.byk/alias/, the files there belong to both the "current directory" and the "global directory". They are scanned in both roles (@f and @@f both work), but they participate in the merge only once, as the global role — they are never merged twice.

    Custom Ordering

    Only write a number when you need to outrank other files in the same directory:

    any .byk.json
    {
      "$priority": 20,
      "build": "vite build"
    }

    $priority only orders same-name collisions; values below 0 are treated as 0. Whether a subtree enters the merged space is controlled by $private.

    Note

    $priority is a reserved field and is never treated as an alias key. When omitted, the current directory uses 1 and the global directory uses 0.

    Visibility

    $private: true keeps a subtree out of the merged space; it stays reachable through exact syntax @file.key / @@file.key.

    Like $cwd and $mode, it has three levels of inheritance: file → group → alias, with the closest level winning. A child can set false to expose its subtree again.

    run.byk.json
    {
      "shared": "echo everyone-can-run-this",
      "scratch": {
        "$private": true,
        "deploy": "deploy --env {env}"
      }
    }

    byk shared still works; byk scratch.deploy is not found and only byk @run.scratch.deploy reaches it.

    To keep a whole file out of the merged space, put $private at the file root:

    local.byk.json
    {
      "$private": true,
      "deploy": "deploy --env {env}"
    }
    Note

    $private only affects the merged space; exact calls always work, including aliases inside a private group.

    Cloning

    $clone: false marks a subtree as personal: ..clone never copies it. It is a copy-time tag only — it does not affect the merged space, execution, completion, or any other lookup.

    Like $private, it has three levels of inheritance: file → group → alias, with the closest level winning. A child can set true to expose its subtree again.

    run.byk.json
    {
      "$clone": false,
      "shared": { "$clone": true, "whoami": "whoami" },
      "deploy": "deploy --prod"
    }

    Cloning this file yields only shared.whoami; deploy is dropped. If nothing would be left, ..clone refuses and writes no file. The tag itself never appears in the copy.

    $private and $clone are independent: write both when an alias should stay out of the merged space and out of cloned copies.

    Note

    $clone only governs byk ..clone. cp, git, and fetching the file by other means still see the original bytes — it is a declaration, not encryption.

    Exact Execution Syntax

    SyntaxDescription
    byk @release.buildbuild from release.byk.json in the current directory
    byk @@release.buildbuild from ~/.byk/alias/release.byk.json
    byk @.buildbuild from the anonymous .byk.json in the current directory
    byk @@.buildbuild from the anonymous .byk.json globally

    Conventions:

    • Pure file routing, no fallback
    • File not found → Alias file not found: @release (@@release on the global side)
    • File exists but cannot be loaded → Alias file cannot be loaded: @release, with the reason and a byk --check hint
    • File exists but key not found → Alias key not found in file @release: build
    • A path segment starts with $ → Not an alias (reserved $ field); $ fields are reserved or custom metadata, not aliases
    • All of these exit with code 1