Alias Configuration
Type Definitions
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
System Fields
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.
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}":
${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.
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.txtandbyk build | grep errorreceive 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.
interactive fits commands with side effects:
$mode inherits through three levels — file, group, alias — with the closest one winning.
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:
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:
Opting in only disables the "same alias re-entered" check; the depth limit still applies.
$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.
When unset, the command itself is shown:
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.
- 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/.binis prepended as well — no need to write either into$pathsyourself - The order of
$pathsis the order inPATH, 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:
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:
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:
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:
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):
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.
Keep the three directories apart:
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
Alias Files
byk reads two locations: the global directory ~/.byk/alias/ and the current working directory (non-recursive).
File Naming
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
Single Link
When the root is an array holding one path, the file is a link file: a pointer to another alias file:
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.
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
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.
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:
$priority only orders same-name collisions; values below 0 are treated as 0. Whether a subtree enters the merged space is controlled by $private.
$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.
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:
$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.
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.
$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
Conventions:
- Pure file routing, no fallback
- File not found →
Alias file not found: @release(@@releaseon the global side) - File exists but cannot be loaded →
Alias file cannot be loaded: @release, with the reason and abyk --checkhint - 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