CLI
Initialize a project and add components with the axiom CLI.
Not published yet
npx axiom doesn’t work yet: the CLI isn’t on npm. This page is the
specification it is being built against, so commands and options may still
change.
The CLI copies source files into your project. It is the only thing Axiom publishes, and it never becomes a runtime dependency of your app: once the files are copied, your app doesn’t need it.
init
npx axiom initpnpm dlx axiom inityarn dlx axiom initbun x axiom initSets up a project for Axiom:
- Asks for the styling tool:
stylesheet,unistyles,nativewindoruniwind. Only the ones the registry has a variant for are offered. - Checks that
tsconfig.jsonresolves the aliases, and offers to add the missingpathsentries (see Aliases). - Copies the foundations (theme, tokens,
light/dark) and the headless core. - Asks, then installs the styling dependency and what the copied files need.
- Writes
axiom.json, with everything it copied listed initems.
Nothing is copied before step 2 passes: a project with half its aliases resolved is worse than one with none.
| Option | What it does |
|---|---|
--styling <tool> | Answers the styling question, for a script or a CI job. |
--install | Installs without asking. |
--no-install | Prints the install command instead of running it. |
--force | Sets up a project that already has an axiom.json. Existing files are kept. |
Aliases
Components are imported through an alias, so init resolves each one through the paths of your tsconfig.json before copying anything. When an alias doesn’t resolve, it shows the entry it would add:
tsconfig.json doesn't resolve @/theme, @/components/core, @/hooks, @/components/ui, @/components/compositions, @/components/blocks.
Add "@/*": ["./src/*"] to its "compilerOptions.paths"? [Y]es [n]oAnswer n, or keep a tsconfig.json the CLI can’t rewrite safely — one with comments — and it asks for aliases your project already resolves instead.
Installing
Before installing anything, init and add list the packages and ask. Answer yes and the CLI says what it is installing, with the command it runs:
Install react-native-reanimated, react-native-gesture-handler? npx expo install react-native-reanimated react-native-gesture-handler
◇ Installing react-native-reanimated, react-native-gesture-handler
npx expo install react-native-reanimated react-native-gesture-handlerAnswer no and it prints the command instead. --install skips the question, --no-install answers no. Without a terminal to ask, init installs and add prints the command.
The CLI uses the package manager of your project, from its lockfile, and goes through expo install when the project has Expo, so the versions match your SDK.
add
npx axiom add bottom-sheetpnpm dlx axiom add bottom-sheetyarn dlx axiom add bottom-sheetbun x axiom add bottom-sheetAdds a component to your project. The CLI:
- copies the variant that matches your configured styling;
- copies missing internal dependencies (
portal,overlay,tappable…); - installs third-party packages such as Reanimated or Gesture Handler;
- never overwrites an existing file without asking (see Existing files);
- registers the component’s tokens in the theme, if it has any (see Component tokens);
- adds the component and every internal dependency it copied to
itemsinaxiom.json.
Internal dependencies are resolved as a graph. Adding bottom-sheet also brings in what it relies on, and skips anything already in your project:
bottom-sheet
│
┌────┴────┐
↓ ↓
portal overlayNames are plain component names. A component that is one file stays one file; one that brings a hook or a subcomponent gets a folder with an index.ts:
npx axiom add button # → components/ui/button.tsx
npx axiom add bottom-sheet # → components/ui/bottom-sheet/pnpm dlx axiom add button # → components/ui/button.tsx
pnpm dlx axiom add bottom-sheet # → components/ui/bottom-sheet/yarn dlx axiom add button # → components/ui/button.tsx
yarn dlx axiom add bottom-sheet # → components/ui/bottom-sheet/bun x axiom add button # → components/ui/button.tsx
bun x axiom add bottom-sheet # → components/ui/bottom-sheet/components/ui
bottom-sheet
Either way you import it the same: import { BottomSheet } from "@/components/ui/bottom-sheet". Its tokens go to theme/components/, not here.
Existing files
Copied files belong to your project, so add protects your changes. A file identical to the registry is skipped silently. When a file differs:
| File | What happens |
|---|---|
| A file of the component you named | The CLI asks, per file: keep yours, overwrite it, overwrite all of the remaining ones, or keep all of yours. |
| A file of an internal dependency already in your project | Kept. add button never touches your tappable.tsx. Name the dependency to update it: add tappable. |
| A file your project owns once created, like the icon registry | Kept, always. |
npx axiom add button --overwritepnpm dlx axiom add button --overwriteyarn dlx axiom add button --overwritebun x axiom add button --overwrite--overwrite replaces the files of the components you named without asking. Dependencies and owned files are still kept, and theme files (theme/, including each component’s tokens) are still asked about, since that is where you customize them. Without a terminal to ask in, they are kept.
Icons
The first item that needs icons asks where they come from (expo-symbols or custom) and saves the answer as icons. Pass --icons <source> to answer without a prompt. When a component draws icons your registry doesn’t have, add lists them. See Icon.
Navigation
The first item that depends on the navigation library, like use-overlay-back-handler, detects it from package.json (expo-router, react-navigation or react-native without one) and saves it as navigation. Pass --navigation <library> to override the detection.
Without a terminal (CI, a script), nobody can answer: differing files are kept and the CLI lists them.
Standalone
npx axiom add tab --standalonepnpm dlx axiom add tab --standaloneyarn dlx axiom add tab --standalonebun x axiom add tab --standaloneFor an app that already has its own design system and wants one component from the catalog. --standalone writes a single file that imports only React, React Native and the npm packages the component uses:
- the Axiom pieces it stands on (Tappable, Text, Icon, its hooks) are inlined;
useTheme()is gone. The file declares athemeconstant with the values of the light theme it reads, and each component’s tokens are typed as in the registry;- nothing else is copied, and
axiom.jsonis neither needed nor written.
The component no longer follows a theme: light / dark and any restyling are yours to handle, in a file that is already yours. What Axiom still guarantees is the behavior: touch targets, gestures, states, safe areas, accessibility.
The file goes where its layer’s alias resolves in tsconfig.json: @/components/ui/tab.tsx for a primitive. Without an axiom.json, pass --styling (stylesheet, unistyles, nativewind or uniwind), or answer the prompt. NativeWind and Uniwind get the same file, with cx inlined next to the components that join class names. A component that draws icons carries its own icon registry, the icons object in the file, filled from the source you pick; add your icons there.
Components that render through a portal (Dialog, Menu, Bottom Sheet, Toast, Snackbar) aren’t available standalone yet: a portal needs a host mounted at the root of the app.
sync
npx axiom syncpnpm dlx axiom syncyarn dlx axiom syncbun x axiom syncBrings your project in line with items in axiom.json. Use it to set up a project with the same items as another one, to restore files that were deleted, or to update what you copied. It needs an axiom.json.
For each item, sync runs the same steps as add: it copies the variant for your styling, resolves internal dependencies, and installs missing npm packages. Files missing from your project are written. Then, when files differ from the registry, it asks two questions:
- Which levels you keep as they are. All of them are checked by default, so pressing Enter overwrites nothing.
- Which differing files of the other levels to overwrite. All of them are checked by default.
| Level | What it covers |
|---|---|
core | The core primitives and the hooks |
theme | The theme folder: tokens, and each component’s tokens |
components | Primitives, compositions and blocks |
Files your project owns once created, like the icon registry, are never overwritten.
Two options answer the questions for you:
npx axiom sync --keep core,theme --overwritepnpm dlx axiom sync --keep core,theme --overwriteyarn dlx axiom sync --keep core,theme --overwritebun x axiom sync --keep core,theme --overwrite--keeptakes the levels to keep, separated by commas, ornone.--overwritereplaces every differing file of the other levels without asking which.
Without a terminal to ask in, what no option decides is kept: sync alone only writes missing files, and --keep without --overwrite lists the files it left alone.
A component you update can rely on a token or a core primitive newer than the one you kept. Typecheck after a partial update.
Configuration
The CLI reads and writes axiom.json at the root of your project: styling variant, aliases, and the list of copied items. See Configuration.