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
Free items need nothing: they come from the public repo with no account. Pro items use the license activated on the machine with login, or KOALAUI_LICENSE and KOALAUI_INSTANCE on CI. A Pro item can depend on free ones, and those still come from the public repo.
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[]- 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
Files that already exist are skipped and listed, so a second run never overwrites your edits. Use update to bring them current.
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
The command exits 0 when the install finished. Any error exits 1 and prints its reason after a cross.
| Exit | Message | Meaning |
|---|---|---|
| 0 | added <items> | Every file was written, or skipped because it already exists. |
| 1 | nothing to add | No item name was passed. |
| 1 | unknown item(s) | A name is not in the registry. Run list to see what is. |
| 1 | is a template, a whole site | Templates start in a new folder with the template command. |
| 1 | would shadow Koala's folder | A flat components/ui/<name>.tsx exists. Delete or rename it, then add again. |
| 1 | is part of Koala UI Pro | A Pro item with no license on this machine. |
| 1 | no activated seat | A license without a seat on this machine. Run login <key> once. |