add

npx koalaui-cli@latest add <item...> [options]

Copy one or more items into your project with every component and lib helper they import, record them in koala.json and install the npm packages they need.

Access

One seat per machine

login <key> claims a seat and saves the key to ~/.koalaui/config.json, readable by you only. Coding agents on that machine share it.

Arguments

item...string[]Required
One or more registry names: components, sections or page examples. Run list to see them. Names are resolved with everything they depend on.

Options

--cwd <dir>path
The project root to write into. Defaults to the current directory.
--overwriteboolean
Replace files that already exist. Without it they are skipped and listed.
--no-installboolean
Write the files but skip the package manager. The packages it would add are printed.
--license <key>string
A Pro license key. Overrides the saved one and KOALAUI_LICENSE.
--instance <id>string
The seat to use. Overrides KOALAUI_INSTANCE and the saved one.
--api <url>url
The entitlement API base. https only, and never saved.

What it writes

components/ui/<name>/folder
The component's source and its index.ts, under src/ in a Vite app.
components/sections/<name>/folder
A Pro section's source.
lib/files
The helpers the items import, such as tv.ts, density.tsx or create-context.tsx.
koala.jsonfile
The version of each item and a fingerprint of each file as written. Commit it.
package.jsonfile
The npm packages the items need and you do not have yet, added with your package manager.

Exit codes

ExitMessageMeaning
0added <items>Every file was written, or skipped because it already exists.
1nothing to addNo item name was passed.
1unknown item(s)A name is not in the registry. Run list to see what is.
1is a template, a whole siteTemplates start in a new folder with the template command.
1would shadow Koala's folderA flat components/ui/<name>.tsx exists. Delete or rename it, then add again.
1is part of Koala UI ProA Pro item with no license on this machine.
1no activated seatA license without a seat on this machine. Run login <key> once.