Nexia CLI

Use create for projects and Apps, and make for code inside an App. Explicit options skip their corresponding prompts; omitted settings are asked interactively.

Getting started

Requires Node.js 22.12+, npm 11.x, PHP 8.5.12+ and Composer.

npm install -g @nexia/cli@alpha
nexia setup --devtools
nexia create project my-project
cd my-project
nexia create app people
cd people
composer install --no-scripts
npm install
nexia make resource Note
nexia dev12345678910

Keep dev running. For a new App, run nexia db migrate from the same App folder in a second terminal. Wait for completion before opening the App. Later file saves do not apply migrations; run the command again when ready.

To join an existing project, run nexia connect <project-id> in an empty project folder and approve in the browser. Clone the required Apps as direct child folders, install their dependencies, then run dev. The project folder is distinct from each App repository. Existing AGENTS.md files are preserved.

Updating the CLI

The updates page shows the published CLI alpha version and release notes. Compare it with nexia --version, which shows the version installed on your machine. The CLI is installed separately from Core and the SDKs.

Run nexia update --dry-run to check the npm alpha channel without installing, or nexia update to review and confirm the exact update. If you installed the CLI with another package manager, update it using that manager. Updating the CLI does not rerun an interrupted App or database command.

All commands

Prefix every command below with nexia.

Plain nexia displays help. nexia create, nexia make and nexia db begin with task selection. Choose with ↑/↓ and Enter; Esc cancels. Terminals without raw input accept a number or value.

Questions and confirmation

Explicit options are validated and never asked again. Missing settings show descriptions and defaults. Invalid answers repeat that question. Disabling navigation skips menu group, icon and order questions. Additional language labels are requested only when that language is selected.

App, resource and page creation end with a summary of settings and destination, followed by create, edit a setting, or cancel. Ctrl+C or EOF cancels. Generation never runs before confirmation. The existing generator preflight runs first. Resource generation skips existing files and registrations; page generation rejects collisions. Existing source is not overwritten. An OS write failure may still require inspecting changes already reported by the generator.

nexia create app people --vendor acme --family people
nexia make resource LeaveRequest --label-ko '휴가 신청'
nexia make page Summary --label-ko '요약' --no-record --no-navigation
nexia help make resource1234

App generation

Questions: folder → code name → package owner → App key → display name → family → table prefix → prerequisites → confirmation.

--vendor acme and --key people produce the packages acme/people and @acme/people. Choose stable identifiers before registration. Creating an App does not register or install it. Existing destination folders are rejected even during dry-run.

Resource generation

Questions: App → code name → Korean display/list labels → optional Chinese labels → record ownership → menu visibility → menu settings → confirmation.

Ownership is distinct from permission. Per-legal-entity ownership does not grant access. English labels derive from code names; omitted Chinese labels retain the existing fallback. Translation generation rules are unchanged; generic --label locale=value is not provided.

Page generation

Questions: App → code name → Korean label → include individual record read/edit screens → menu visibility/group/order → confirmation.

Options are --label-ko, --record / --no-record, --navigation / --no-navigation, --navigation-group and --sort. Record screens and navigation default to enabled, group to operations, and order to 100. A page creates no model, migration or Resource. Implement its business query before use.

Menu groups are insights, management, operations, master-data and settings. Menu detail options cannot accompany --no-navigation. Duplicate options and contradictory booleans are errors. Field/relationship designers and force-overwrite are not provided.

Folder and App selection

Commands also work in App subdirectories by finding the parent App/project. Explicit --app <folder-or-key> wins; otherwise the current or only App is selected. Multiple project Apps trigger a selection question.

dev offers all Apps, saved Config Apps, or individual Apps, up to 20. Use nexia dev config to save a default selection; repeated --app options explicitly select Apps. dev --app people develops one App. The default port is 4310; override with --port. Use --container for container preview access. Project Apps share one port; new Apps join automatically only when All Apps is selected. Without an interactive terminal, use repeated --app options to restrict the selection; saved Config Apps are not automatically applied. Duplicate identities and symlink folders are not run.

dev handles registration, sandbox preparation, source synchronization and frontend watching. Source limits are 2000 files, 2 MiB per file and 16 MiB total; secrets, dependencies and symlinks are excluded. Sandbox retention is 100 revisions/512 MiB. Data is never automatically reset. Ctrl+C stops local watching. Remote runtime management stays in Developers; an existing writer lease or pending preparation may prevent a new development writer.

Authentication

login uses the current folder's project or asks for a project ID. Browser approval remains project-scoped, not account-wide. connect authenticates and binds the folder; create project also includes approval. --no-browser prints the approval URL. logout retains folder bindings and data. status reports mismatched authentication and folder scope; Apps are never silently moved between projects.

The official platform is https://developers.nexia.to. Platform developers can set NEXIA_ENDPOINT for login, connect and create project. Re-authentication for an already bound project prefers its saved endpoint. Endpoint changes clear old authentication. Never share or commit .nexia/ or the global CLI credential file.

Environment setup

setup --devtools installs/updates generators in the CLI-owned directory, without changing global Composer. setup asks whether to also install/upgrade Homebrew PHP and Composer on macOS and confirms the plan. Existing runtime versions may change; this redesign does not alter upgrade policy. On Linux/Windows install prerequisites yourself, then use --devtools. --dry-run performs no installation; shell startup files are not automatically edited.

Database and submission

Run nexia db access from the connected project root or an App folder inside it. One personal sandbox account can read and write all managed App data. The CLI shows IP registration, server/gateway progress and elapsed time, then prints connection details and an App name → schema name list. Core data, database administration and App schema DDL are excluded. Use existing App CLI commands such as nexia db migrate for schema changes.

Create one PostgreSQL connection in DBeaver using the printed Host, Port, Database, User and Password. Select SSL verify-full and keep the printed hostname. Find each App in App schemas. New managed App schemas include the App name, such as dev_people_<identity>; existing schema names and data are preserved. This does not install PostgreSQL or create a database on your computer.

The account is separate from App runtime credentials. Stopping nexia dev or replacing an App execution does not replace it. Reuse the connection while the sandbox and your development access remain valid. New App schemas receive access during server synchronization; subsequent migration tables receive DML privileges automatically. Refresh DBeaver's schema list; do not rerun db access for every new App. Data stored in an App's local PostgreSQL database is not part of this server connection.

When watching all Apps, nexia dev discovers an App created with nexia create app in another terminal. If watching selected Apps, restart with a selection that includes the new App. After registration and database preparation, run nexia db migrate in that App's folder.

Use nexia db access --ip <public-ipv4> when your SQL client's public address changes, or nexia db access --revoke to close this personal sandbox SQL account's external connections while retaining data. Sandbox expiry/deletion or removal of development access ends access. Replace old per-App connection details with the new sandbox account. The new CLI requires matching Core and database gateway updates.

To keep App data in PostgreSQL on your computer, follow Use local PostgreSQL for a development App before the App's first run. nexia db local prepares the dedicated local database, and nexia dev maintains its tunnel. It does not move data from an existing Nexia-managed allocation.

nexia dev watches source without applying migrations or initialization. Keep it running while writing migration files. From the App folder in another terminal, run nexia db migrate when ready. The command uploads the current local source, pins that revision, and waits for completion; the watcher then resumes. A new App waits for its first explicit migration without administrator review. Development migrations can be rolled back, edited and run again. Published files remain immutable.

Project root commands target all Apps sequentially; --app=people selects one, and an App folder selects that App. Failures do not skip later Apps. db status shows migration files, batches, changed/missing/interrupted diagnostics and the last command without booting App providers. db rollback reverses the last batch (--step or --batch selects a range), db reset runs all down() methods, db refresh rolls back then migrates, and db fresh erases the selected development schemas then migrates. Destructive commands confirm the selected Apps once. db seed runs an App Seeder (--class selects its class); db seed <key> keeps fixture behavior. Refresh/fresh support --seed. Migrate/rollback/reset support --pretend; SQL literals are redacted. migrate --step creates one batch per file. Keep dev running, correct errors and explicitly rerun the command. After nontransactional failure, inspect and repair the App database; changing the source or running fresh is not required. Preserve published migration history: submit checks published files, not the current development DB. If the manifest itself cannot load, status still shows applied records and conventional migration paths with an incomplete-inventory warning. New commands require matching CLI, Core and Manager versions.

Commit and push source and the intended version tag with Git, then run check and submit --tag v1.0.0. If repository connection is missing, interactive submission guides you to Developers approval. Automated callers must connect it first. The CLI does not commit, tag or push. Submission requests review, not deployment or installation. Use the returned ID to inspect status; cancellation/retry follow server state and authorization. New source requires a new tag. With Core 0.8.172, a transient platform test error is also eligible for the existing retry action when the server confirms the submission is retryable. Original evidence is retained and mandatory checks run again.

Run development data

Only fixtures declared by your App are available. Keep nexia dev running and apply migrations first with nexia db migrate. Run these commands in the App folder. The first command asks you to choose data and confirm execution:

nexia db seed
nexia db status12

Use nexia db seed <key> when you know the fixture key. The command waits for completed; then inspect the records in your App. Wait for queued or running; correct failed commands and explicitly run them again. Check the fixture implementation before repeating a data run.

For column changes, follow the application steps in Data Model and Migrations.

Automation and recovery

Non-TTY execution does not prompt. Optional values use documented defaults. Dry-run skips final confirmation because it performs no changes.

nexia make resource Note --app people --label-ko '메모' --no-interactive --yes
nexia submit --app people --tag v1.0.0 --no-interactive --yes --json
nexia submit status <submission-id> --json123

JSON mode writes one result or error.code/error.message to stdout; diagnostics go to stderr. Exit codes are 0 success/acceptance, 1 operation failure, 2 input error, 130 cancellation. Zero does not establish asynchronous job completion.

Recover expired authentication with login from the project. After a lost project-creation response, retry the same folder/name to resume pending approval without creating a different project. Fix source/build errors and restart dev; do not reset data as a repair shortcut.

Migrating old commands

Replace init with create app, create-project with create project, link-project with connect, make:resource/page with make resource/page, validate with check, and submissions with submit. Run in the intended folder or use --app instead of trailing App paths. Replace --without-navigation/record with --no-navigation/record.

Manual registration, sync, runtime, repository and doctor commands, browser templates, DB reset/references, cross-App fixtures, resource catalogs, signature generators, Filament options, Runtime image inspection and local MCP are excluded from the public CLI. Existing platform/SDK/internal implementations are not deleted. Manual one-shot snapshots and MCP through nexia are no longer provided; synchronization remains in dev. Do not assume every excluded command has an equivalent Console action. Existing PHP devtools signature/Filament generators remain available to their callers.

CLI developers can point NEXIA_DEVTOOLS_PATH at an independently installed generator with its Composer dependencies prepared. The executable cannot reside inside the App being generated/checked. Support requests should include sanitized reproduction and versions, never credentials or customer data: Developer Support.

For relationships to Core tables, see Reference Core identities from App tables for the allowed targets and checks before saving.

Declare a fixture and verify replay before running db seed <key> for your own App.

Documentation access

nexia docs works without login or a project. Use --locale en|ko to select the edition and --json for structured output. See Work with a coding assistant for task-specific contracts, source languages, search limits, and SDK version checks.

Recent submissions and terminal navigation

Run nexia submit status without an ID to choose a recent submission by App, tag, status and creation time. Use ↑/↓ and Enter, or Esc/Ctrl+C to cancel. The picker can load older pages. nexia submit list --page 2 prints a page with IDs. From an App folder results are App-scoped; from the project root they cover that project. Without an interactive terminal, status without an ID returns the list. Cancel/retry require an explicit ID in automation and retain confirmation. Help is grouped by task, selections are highlighted, and NO_COLOR/TERM=dumb turn off colors. Piped and JSON output remain plain.

connect binds the folder and signs in; login renews CLI access for that folder. stop stops tracked local watchers and preview servers. logout revokes CLI authentication, leaving local processes, project bindings, sandbox/workspace data and browser login intact. Use stop, then logout when both are intended. Resume with login if needed, status, then dev; restart any watcher that started with the previous login. Expired credentials do not block status/logout. Neither command deletes the sandbox or workspace; their lifecycle is managed separately in Developers.

Recover a failed source update

CLI 0.2.0-alpha.47 includes detailed preparation errors and recovery after a confirmed execution stop. Run nexia update, check nexia --version, then start the same App selection with nexia dev. If a source update fails, retain its operation/update ID, source revision, full error and Details URL when supplied. Add --verbose to your existing development command to inspect the relevant failure.

Core 0.8.163 and compatible runtimes let the next source save proceed when the previous update was safely reverted. Uncertain updates and Waiting for execution to stop still need confirmed server state; local watching or removal of a stale local record is not proof of readiness. Do not reset the database, lower SDK requirements or remove cleanup safeguards. Verify Development ready, a later source save and an authorized App read before calling the execution recovered.

See GitHub preparation-error details and the published CLI release.