File Commands
Every alias file carries a set of reserved commands for creating, editing, and inspecting the file itself:
.. is the reserved separator. A token that starts with @ / @@ and contains .. is never treated as an alias, so byk @@ops..set always runs a file command instead of looking up an alias named @@ops..set.
Addressing
- A file name cannot contain
.,@,/, or spaces; letters, digits,-,_, and CJK are allowed. - The first
..is the separator; the command name after it may only contain letters, digits,-, and_. - Mutating commands only write the addressed file; sources of
clone,link, andinit --linkare read-only. ..setand..removerefuse to rewrite a link file (single-element array); edit the link target instead...clearempties the link file itself.- When a command that requires the file finds it missing but the other side (current or global directory) has a file with the same name, the error suggests switching the prefix;
..pathdoes not require the file to exist. - Mutating commands print status to stderr;
json,path, andhelpwrite data to stdout, so pipes and$(...)work as expected.
Command Index
Creating and Deleting
..init
- Contents are always
{}plus a trailing newline; an existing file is never overwritten. --link <source>creates a link file (a single-element array) holding the source's canonical absolute path.- The source may be
@name(current directory),@@name(global directory), or a path (~expands, relative paths resolve from the current directory). It must be an existing object alias file; a link file is rejected because links support only one level. - A bare local name is literal first and falls back to
.byk.json;.,.., a trailing/, or a directory name reads that directory's.byk.json— the same local rules as..clone. - Creating a global file creates
~/.byk/alias/when it does not exist.
..destroy
- Deletes the addressed file. Interactive confirmation asks you to type the file name; non-TTY environments must pass
--yes. - A symlink removes only the link itself, leaving its target untouched; directories are refused.
- For a global file, the dependency directory
~/.byk/deps/@@<file-name>is removed along with it.
..clear
- Resets the file to
{}. An already-empty file only reportsAlready emptyand is left alone. - Clearing a link file empties the link file itself; the target is untouched.
- Clearing a symlink is refused — use
..destroyto remove the link. - Like
..destroy, non-TTY environments require--yes.
Editing Aliases
..set
The first argument that does not start with - is the alias key; dots express group paths, and missing intermediate groups are created automatically.
Alias options:
File-root options (no key):
- Adding metadata to a string alias converts it to the
{ "$cmd": ... }object form; removing the extra metadata folds it back to a string. --privateis inheritable;--no-privatewritesfalseon a child to re-expose it inside a private group. See Visibility.- A key cannot start with
$; use the options above for metadata instead of writing it into the key.
..remove
- Removes an alias or an entire subtree by dotted path.
- A group left with only
$metadata is pruned as well. - A missing key is an error, never a silent success.
- To remove a single metadata field, use
..set <key> --unset <fields>.
Inspecting
..json
- The default validates JSON but prints the exact original bytes: no reordering and no added newline.
--no-checkskips validation entirely and prints even invalid JSON.--expandexpands built-in and file$varvariables, removes$var, and pretty-prints; variable problems go to stderr.--expandand--no-checkcannot be combined.- A link file prints the array itself; the target is not followed.
..path
Prints the absolute path. The file does not need to exist, and the command takes no arguments.
..rename
- Renames within the same scope (
@only affects the current directory,@@only the global one). - The new name follows the same file-name rules; an existing target is refused.
- For a link file, only the link file is renamed; its target is untouched.
- For a global file, the dependency directory
~/.byk/deps/@@<old-name>is renamed to@@<new-name>along with the file, so${deps_dir}keeps pointing at the right place.
..help
An unknown command lists every available file command.
Cloning and Linking
..clone <source>
Sources:
Repository shorthand shape:
@<ref>is optional and defaults toHEAD.<path>is optional: leaving it out reads the repository root.byk.json, souser/repoequalsuser/repo/.- A
<path>pointing at a directory must end with/, meaning that directory's.byk.json. - The last segment is the file name; the
.byk.jsonsuffix is optional. - The sugar covers the whole path only:
user/repo/ssstill readsss.byk.jsonand is never guessed to be ass/directory. - Don't include a host.
-gh github.com/user/repowould be read asuser=github.com, so it fails outright with a hint to writeuser/repo.
Local path resolution:
-
A bare name is literal first:
./toolreadstool, and only falls back totool.byk.jsonwhentoolis missing. So both stay reachable when they coexist — writing./tool.byk.jsonalways addresses the alias file. -
Only names that could legally be an alias file name get the suffix:
hello.txtormy toolstay literal and are never probed ashello.txt.byk.json, which would not be a valid alias file name anyway. -
When a bare name resolves to a directory, that directory's
.byk.jsonis read, so./tools,./tools/and.all address the anonymous file. -
..linkand..init --linkresolve sources exactly the same way. -
When nothing matches, the error lists every candidate:
Source not found: …plusAlso tried: …. -
The destination must not exist;
..clonenever overwrites. -
A local source is validated first: it must be a JSON object, and a link file (array) is rejected.
-
The result is an independent copy with no relationship to the source. Use
..linkfor a live reference. -
Aliases and groups marked
$clone: falseare dropped from the copy; marked groups keep children that re-expose themselves with$clone: true, and the tag never appears in the result. If nothing would remain, the clone is refused before writing. A copy that strips anything, or carries a tag at all, is re-serialised with keys sorted.$privatedoes not affect cloning. -
Either source freezes
$deps.baseinto an absolute address and printsRecorded $deps.base = …. The form follows the source: remote writes an absolute http(s) directory URL, local writes a local absolute directory path. The fill-in rules are identical — the source file's directory when absent, resolved against the source file when relative (./..//sub/dir), kept as-is when already absolute with only the trailing/added. -
$deps.baseis a best-effort anchor written by the program, not a portability guarantee. Each clone in a chain (a ← b ← c) re-freezes it, so the original source semantics can be lost. Don't hand-write it. -
Neither form crosses into the other: a remote source rejects a local-path
base(/x,C:/x), which is why an alias file taken from the network cannot read local files; a local source keeps an absolute URL as-is, and those assets still come off the network. -
A
basecontaining variables fails outright: a clone has no variable table, so${CDN}cannot be evaluated and guessing would bake a bogus address into the file. Writing it back re-serialises the whole document (keys sorted); files with neither$depsnor$clonestay byte-for-byte copies. -
Remote sources require
curl; without it you get an install hint. A 404 reportsRemote source not found: <url>with a hint to check the repository, ref, and path — a directory path missing its trailing/lands here too. -
Options may come before or after the source:
-gh user/repo@v1/tool -dequals-d -gh ....
Tap index (--tap)
A repository can publish many alias files without keeping them all at the root: --tap reads a routing table named byk.tap.json from the repository root.
The index is a flat JSON object. Keys starting with $ are reserved for metadata and never match:
- Tap source shape:
<user>/<repo>[@<ref>]/<key>.<ref>defaults toHEAD;<key>is exactly one path segment and cannot contain/, be.or.., or start with$. --tapis GitHub-only and is itself a source form: it cannot be combined with-gh,-ge, or-jd.- Local index first (full form). Byk reads
~/.byk/tap/<user>/<repo>/byk.tap.jsonwhen the spec has no@<ref>. When that file exists it is authoritative: parse errors, a missing key, a non-string entry, or a missing target all fail; only a missing index file falls back to GitHub. An explicit@<ref>always uses the remote index. - Single-key shorthand.
--tap <key>with no/searches every valid~/.byk/tap/<user>/<repo>/byk.tap.jsonwithout fetching an index from the network. A unique match is cloned from that local index (a URL value still uses the remote clone path); when several repositories contain the key, the command lists the full formsuser/repo/keyand asks you to pick one; when none contain it, the command fails without any remote fallback. - The shorthand reads exactly two levels:
tap/<user>/<repo>/byk.tap.json. Directory names must be valid GitHub usernames / repository names; invalid names and directories without an index are skipped. Unreadable or invalid indexes are reported as warnings and skipped, so uniqueness only covers readable indexes. - The shorthand has no
@ref; use the full form to pin a ref, which reads the remote index. ~/.byk/tap/is a read-only cache: byk never creates, updates, or deletes it. Populate it yourself, for examplegit clone https://github.com/user/repo ~/.byk/tap/user/repo.- Values are literal pointers; no
.byk.jsonsuffix is added and directories are not followed. A target starting with@or@@is a literal file name, never an alias reference.- Local index: a relative value resolves from the index's directory; absolute paths and
~are local files;http(s)URLs still use the remote clone path. - Remote index: a relative value resolves from the repository root; only
http(s)URLs and repository-relative paths are allowed, never local paths.
- Local index: a relative value resolves from the index's directory; absolute paths and
- Only one level is routed. The target must be an alias file, not another tap index: a target whose last segment is
byk.tap.jsonis refused, and the resolved file is never followed as a second route. $deps.baseis anchored on the target's location, not the index. A local target freezes it to a local absolute directory inside the cache; a URL target keeps the http(s) directory URL.- A missing index reports
Tap index not found: …with a hint to addbyk.tap.json; a missing key lists the available keys. - Byk prints which index it used before routing:
Tap index: local <path>orTap index: remote <url>, followed byTap <key> -> <target>.
Clone and install dependencies (-d)
- After the file lands, byk reads the new file's
$deps: if present it runs the same sync as..deps i(a fresh key has no manifest, so it is a first install); if absent it is skipped rather than treated as an error. -dis global-only — dependency directories are keyed by the global file key, so a local destination is rejected before anything is downloaded.- The install step never asks twice and needs no
--yes: clone-to-assets-fetched is a single command, which suits scripts and non-interactive shells. - A failed install does not roll back the clone: the file is already valid, so rerun
@@<file>..deps ias suggested; assets already in place are never downloaded twice.
..link <target>
- Rewrites the addressed file into a single-element array pointing at the target's canonical absolute path.
- Works only on an empty
{}object or a file that is already a link; a non-empty alias file is refused. - The target must be a local object alias file; a URL is rejected with a hint to use
..clone. Local names follow the same rules as..clone: literal first, then.byk.json, with directories reading their.byk.json. - Pointing at itself is refused, and symlinks are not rewritten.
- When the addressed file is missing, the error suggests
..init --link. - When retargeting a global file whose dependency directory already exists, byk suggests running
..deps uninstallfirst so you keep using the old target's assets. - For link behaviour, path resolution, and identity rules, see Single Link.
..deps [install|uninstall|status]
The subcommand is one of install / uninstall / status, and unambiguous prefixes are accepted; no subcommand means status.
install syncs, it does not append. $deps.files is the desired state, and installing converges the directory to it:
When no file entry changed and no packages are declared, it is a no-op and never touches the network:
- A relative
srcis joined with$deps.base; either one alone is an error, never a guess.basemust be absolute on disk — the URL form means download, the local-path form means copy, and..clonepicks it by source. Its relative forms only mean something at clone time. The program writesbase; it is a best-effort anchor, not a portability guarantee, so don't hand-write it. - Local entries are compared by source mtime: a newer source is reinstalled, a missing one fails with
cannot readand its path instead of being skipped. - Works for global and local files alike: global assets land in
~/.byk/deps/@@<file-name>/, local ones in<file-dir>/.byk/deps/@<file-name>/with a self-ignoring.gitignore(*). - The install manifest lives at
<dedicated directory>/.byk-deps.jsonand records the last declaration plus where each asset landed. Deleting it just restarts the bookkeeping; the next install adopts whatever is already there. - Only paths byk installed are ever removed: anything else in the directory is left alone with a warning.
- The install step never asks twice and needs no
--yes;--forceis the only option, for cases the manifest cannot detect (assets corrupted from outside). - Absolute addresses are fetched with the system
curl, local paths are copied withfs::copy(same temp-file-then-rename dance); extraction is delegated to the systemtaron both paths, and a missing tool errors with an install hint. The summary saysDownloadedeither way and counts the local ones in parentheses (Downloaded 3 files into … (1 local)); a run with nothing local has no parentheses.$deps.filesonly fetches files;$deps.pipand$deps.npmare handed to pip / npm themselves and are not part of the file manifest. $deps.pipinstalls Python packages into.venvinside the dedicated directory: the venv is created withpython3(pythonon Windows) when missing, thenpip installruns. The venv'sbin/Scriptsis prepended toPATH; a missing Python fails with an install hint.$deps.npminstalls npm packages into the dedicated directory: a minimalpackage.json(byk-deps,private) is written when absent, thennpm installruns.node_modules/.binis prepended toPATH; a missing npm fails with an install hint.- Packages install on every run and are not tracked by
.byk-deps.json— pip / npm decide what is current.--forceonly affects file entries, and removing a spec from the declaration does not uninstall it;..deps uninstallclears the whole directory.filesis optional, so a declaration may contain only packages. - Everything lands inside the dedicated directory (
~/.byk/deps/@@<file-name>/globally,<file-dir>/.byk/deps/@<file-name>/locally). See Dependencies for the field reference. - An
extractentry lands on a directory and is marked(extract); reinstalling replaces the whole directory, so files dropped from a newer archive never linger. Withouttoit unpacks into the dependency root, which only works as the sole entry (it replaces that whole directory):
- A mid-run failure does not roll back finished entries; the error lists what already landed this run, and the manifest is written to match, so rerunning continues where it stopped.
- uninstall deletes the whole dependency directory; a missing directory is an error. status is read-only and writes to stdout, so it pipes well:
unknown marks a pip direct reference (URL / VCS): its package name cannot be determined locally, so byk reports it instead of guessing. Unknown entries count as neither present nor missing.
--check only validates the declaration itself: whether it parses, whether two entries collide on one target, whether a relative src has a base, and whether package entries are non-empty strings. It never looks at what is installed — missing or outdated assets are runtime state, reported by ..deps status.
Completion
File-command completion covers:
- file names after
@/@@, and command names after..; - options after a command (for example
..set --); - command names after
..help; - existing key paths after
..remove(read from the target file; link files are not completed); - source arguments for
..clone,..link, and..init --link(alias files starting with@); - subcommands after
..deps(install/uninstall/status).