rmb32 / barnark-cli
The command-line delivery mechanism for Barnark — the template commands (list, new, clone, copy, delete, offers, check, add-folder, change-meaning).
Requires
- php: ^8.5
- rmb32/barn-paths: ^0.3@dev
- rmb32/barnark: ^0.3.1@dev
- symfony/console: ^8.0
Requires (Dev)
- infection/infection: ^0.35.4
- phpstan/phpstan: ^2.2
- phpunit/phpunit: ^13.3
- rector/rector: ^2.6
- rmb32/barnark-gui: ^0.2.11@dev
- rmb32/barntree: ^0.1.5@dev
- rmb32/typed-json: ^1.0@dev
- squizlabs/php_codesniffer: ^4.0
Suggests
- rmb32/barnark-gui: Adds `barnark gui`, which serves the browser UI and opens it
Provides
None
Conflicts
None
Replaces
None
README
Early, version 0.x. Not ready for real projects yet; the minor version is the breaking one.
Part of Barn.
The barnark command: copy an architecture template into your project, make a folder to a copy of it,
and check that the folder keeps to it. Built on
Barnark.
Working with an AI agent? Run vendor/bin/barnark skills:install first. It gives your agent skills for choosing an architecture, designing a template and placing code by the folders' meanings. See Agent skills.
Requirements
Requires Barnark core 0.3 through its installed dependencies; stored barns need no conversion.
- PHP 8.5+
Installation
composer global require rmb32/barnark-cli # once, for every project
# or per project
composer require --dev rmb32/barnark-cli
Usage
barnark init # make a barn here (the .barn/ folder) if there is none
barnark template:list # the project's arks' templates, your own and the shipped ones, and where each copy came from
barnark ark:list # the project's arks: name, folder and template
barnark template:components Library # the components a template is built from, placed or only available
barnark template:copy-component Library Features "My Library" --name=Modules # a copy, available to place, with what it holds
barnark template:remove-component "My Library" Modules # takes an available component out again
barnark template:place "My Library" Internal Modules # place an available component in a folder of the template
barnark template:copy "Domain Driven Design" "My DDD" # copy a shipped template into one of your own
barnark template:clone "My DDD" Shop ./src # make the ark "Shop" in src/ from a copy of My DDD
barnark template:check Shop # check the ark "Shop" against its template
barnark template:offers src/Context # what can be created in this folder?
barnark template:new Context Billing src/Context # add a member to the template and make its folders
barnark template:add-folder src/Docs "Design notes." # add a folder of your own to the template, or take one in
barnark template:change-meaning src/Docs "Notes." # change what a folder of the template means
barnark template:add-folder Api/Http "HTTP." --template="My Library" # add a folder to one of your templates
barnark template:add-list "My Library" --in=Project --name=Contexts --meaning="One folder per context." --member-type=Context --member-meaning="A part of the business." # a list of your own
barnark template:add-folder Domain "What a context knows." --template="My Library" --in=Context # build inside a member type, by key
barnark template:remove-folder "My Library" --in=Infrastructure # take a folder out of the tree; it stays available (--delete-definition deletes it)
barnark template:tag "My Library" --in=Contracts --tag=Domain --meaning="What the app is about." # tag a folder of your template
barnark rule:set Shop Domain '*.php' '*.ts' # the files the folders tagged Domain may hold, in the ark "Shop"
barnark rule:list Shop # the ark's file rules
barnark template:copy Shop Invoicing # copy a template into a new one of your own
barnark template:delete Invoicing # delete the copy
barnark gui # serve the browser UI and open it (needs rmb32/barnark-gui)
A project can have many arks: each is a named folder that follows a template of its own.
template:clone makes one from one of your own templates: it copies the template as the ark's own,
named after the ark (or after the ark with a number, "Shop 2", when one of your templates has that
name), and makes a folder for each member it has. A shipped template is refused: copy it into your
own with template:copy first. The ark's name must be unique in the project, ignoring case, and
follows a template name's rules: no leading or trailing dot, and none of / \ : * ? " < > |. The
copy is tied to nothing, so a later change to the template it came from never reaches it. The folder can sit anywhere on your computer: for one outside the project's
root, add --outside. The ark's folder holds a small .barn-ark.json that points back to the
project; its paths are relative unless you add --absolute-link. Commands that act on an ark take
its name with --ark, or find it from a path inside it, and refuse when the two disagree.
--dry-run checks the template, the ark's name and the target, and prints the folders it would make. The
folder above the new one must exist.
Your own templates come from template:copy, which copies a shipped template or one of yours; nothing is copied out of an ark. Shipped templates are read-only. Blank project is one shipped template with a single
empty folder, src, for a project whose shape is still to be decided. Deleting one of
your own asks first, since only git brings it back (-n goes ahead without asking).
The project remembers its arks, each with its folder, in .barn/barnark/tracked-folders.json,
and keeps each template, an ark's or not, with every revision, in .barn/barnark/catalogue/. Don't
edit those files by hand: a template changed outside Barnark can't be read.
template:check also says when an ark's link file and the project's record disagree: a folder moved,
a link deleted, or a link that points at another project. It reports and never repairs.
The barn
Barnark keeps its records only in a barn: the project's .barn/ folder, which every Barn tool shares.
barnark init makes one in the current folder (and asks first inside another barn; -n refuses
there unless you pass --separate-barn). With no barn, every template: command refuses and writes
nothing, and barnark gui serves a page that offers to make one. Each template: command prints the
barn's root first, and works from any folder inside it. Folder paths
are relative to the barn's root. An ark's folder can be named the way the GUI shows it, from the root
(barnark template:check /src), or by the ark's name.
cd src/Context
barnark template:new Context Shipping . # added to the template in .barn/barnark/catalogue/
barnark template:check --ark Shop # checks the ark "Shop"
template:check checks a real project's own contexts, features and aggregates
where they actually are. A template's parts are the folders it names itself;
its slots are what your own folders fill. Where the template leaves a
folder no choice (every folder in Context/ is a Context), it is checked as
filling that slot, and that works for an explicit template and directory too.
A member added with template:new or the GUI is in the template, so if its folder is deleted by
hand the check reports it as missing. Files are never
checked: a template says only what folders there are.
The same template says what may be created in a folder, which is what
template:offers reports and template:new acts on:
$ barnark template:offers src/Context/Billing/Domain
----------- ----------- -------------------------------------------------------------
Slot Key Create it with
----------- ----------- -------------------------------------------------------------
Aggregate Aggregate barnark template:new Aggregate <name> src/Context/Billing/Domain
----------- ----------- -------------------------------------------------------------
$ barnark template:new Aggregate Invoice src/Context/Billing/Domain
template:new adds a member you name to the template, as a new revision, then makes its folder
with whatever fixed structure the slot carries — a Context arrives with its Domain,
Application, Infrastructure and PublicApi. Barnark adds .gitkeep to empty folders so git
can track them. A member already in the template is refused.
A folder of your own goes into the template with template:add-folder <path> <meaning>: a new
revision with the folder in it, saying what belongs there, then the folder. A folder already made
by hand is kept as it is, so this is how one template:check reports as unexpected is taken in.
template:change-meaning <path> <meaning> changes what a folder of the template, or an ark's folder
itself, means. A collection holds only members, so a folder inside one is refused, and so is a
folder the template uses in several places, since changing it would change it in each.
Both take --template=<name> to change one of your own templates instead: the path is then read
inside the template's folder, and nothing is made on disk.
In one of your own templates a folder is reached by its component's key, as template:components lists
it (--keys prints only the keys), which reaches what a path can't: the inside of a member type, and a
component not placed yet. template:add-folder <name> <meaning> --template=<name> --in=<key> adds a folder
inside it, and template:change-meaning <meaning> --template=<name> --in=<key> changes what it means.
template:add-list adds a list: a folder for the members, and the member type each follows, an empty
folder to build inside. template:remove-folder <template> --in=<key> takes a folder out of the tree,
with everything inside it; it stays available to place again, or goes with its definition under
--delete-definition. The root, a member type (it goes with its list) and a folder used in several places
stay. An ark's template takes none of these beyond a folder it names itself: it holds members, so its
shape only grows.
A component copied with template:copy-component is available until template:place <template>
<path> <component> puts it in the folder at <path> inside the template's folder ("" for its
top), under its own folder name. In an ark's template its folder and every fixed folder inside it are
then made, one already made by hand being taken in; a collection arrives empty, ready for members.
A component is placed only once, and never in a collection or a folder used in several places.
Tags and file rules
A tag says what part a folder plays, such as a layer, and a rule says which files the folders carrying a tag
may hold. Tag the folders of one of your templates before you make an ark from it:
template:tag <template> --in=<key> --tag=<tag> --meaning="..." puts a tag on the folder of the component
<key> (the meaning is needed only when the template doesn't declare the tag yet), and template:untag takes
it off. Tagging or untagging a shared component reaches every occurrence, and the confirmation lists
those places in the template. <Feature> denotes a member type, (root) the template's top folder;
an available component has no occurrences yet. A tag belongs to that component's folders alone, not
to the folders inside them. An ark keeps the tags its template had when it was made.
Then give the ark a rule: rule:set <ark> <tag> <pattern>... says each file directly in a folder carrying the
tag must have a name that matches one of the patterns (*, ? and [...], capitals counting). Quote each
pattern so the shell leaves it alone; --none makes a rule that allows no file. A file whose name starts with a
dot is never seen, so a folder holding only a .gitkeep is empty. rule:list <ark> shows the rules and
rule:remove <ark> <tag> takes one away. Each ark's rules are in .barn/barnark/rules/<ark>.json: commit it,
and Git keeps its history. template:check then reports each file that doesn't match, in its own group, and a
rule for a tag its template doesn't declare.
A folder offers nothing when it holds only fixed parts (the root of a
Domain Driven Design folder is all Kernel/Transport/Context), or when
the template names nothing inside it, or when it sits outside the template.
Run barnark <command> --help for every option.
| Command | Purpose |
|---|---|
init | Make a barn in the current folder, or name the one it is the root of |
ark:list | List the project's arks: name, folder and template |
template:list | List the arks' templates, your own and the shipped ones, each copy with where it was copied from |
template:components | List the components a template is built from, placed or only available, or show one |
template:copy-component | Copy a component, with what it holds, into one of your templates or an ark's, available to place |
template:place | Place an available component in a folder of one of your templates, or an ark's, making its folders in an ark |
template:remove-component | Remove an available component, with what only it holds |
template:clone | Make a new ark and its folder from a copy of one of your templates, named after the ark |
template:check | Check an ark against its template, or a directory against a shipped template |
template:copy | Copy a template into a new one of your own |
template:delete | Delete one of your templates, with every revision |
template:offers | List the slots a folder's template says can be filled inside it |
template:new | Add a member the folder offers, under a name you give, to the template and the disk |
template:add-folder | Add a folder of your own to the template, or take in one made by hand; in one of your templates, by key |
template:add-list | Add a list of your own, with its member type, to one of your templates |
template:remove-folder | Take a folder out of one of your templates, keeping or deleting its definition |
template:change-meaning | Change what a folder of the template means |
template:tag | Put a tag on a folder of one of your templates, declaring the tag with a meaning if it is new |
template:untag | Take a tag off a folder of one of your templates |
rule:set | Say which files the folders carrying a tag may hold in an ark |
rule:list | List an ark's file rules |
rule:remove | Take away an ark's file rule for a tag |
Agent skills
If you work with an AI agent, copy Barnark's agent skills into your project:
vendor/bin/barnark skills:install
That puts four skills in .claude/skills/, the folder Claude Code reads (--dir=<folder> for another
agent's). They teach your agent what Barnark keeps, the commands that read and the ones that write, how to choose an architecture, how to write a template and its folder meanings, and where code belongs. Ask it to set up a new project, add a module, review a change against the template, or explain a failed check: it reads your template first, shows you what it would create, and writes through the commands only once you agree.
Run it again after updating Barnark: files you have changed are kept unless you pass --force.
Related packages
- Barnark — the core library and template catalogue.
- Barnark GUI — the same operations in a browser.
- Barntree — what the templates are written as.
More docs
Internals · History · Known issues
License
Proprietary. See LICENSE. Copyright (c) Roger Barnfather.