Commands

neos setup

This command sets up the development environment.

Important

You must run the command after installing or updating the Neos CLI.
It must be run as an administrator. The command can launch installation programs that create environment variables (e.g. dapr). After initializing Neos with the neos setup command, you'll need to use a new terminal for these to be usable.

The command does the following:

• Checks and installs, if necessary, the .NET SDK and runtime.
• Checks the version of Node and NPM.
• Generates a development certificate and on Windows and associates it with the HTTPS port.
• Checks the HTTP.SYS URL reservation (only on Windows).
• Installs and configures Dapr.
• Installs or updates the global Neos Copilot agent (same behavior as neos agent install). Pass --skip-copilot-install to skip this step.

neos init

This command initializes a new cluster in the current directory.

Three files are created :

• [DirectoryName].yml : Cluster YAML configuration file.
• [DirectoryName].auth.yml : Cluster YAML authentication configuration file.
• [DirectoryName].connectionstring.yml : Cluster YAML database configuration file.
• dotnet-tools.json : .NET tools manifest file.

When a neos command is executed in the cluster folder containing the dotnet-tools.json file, the tool with the specified version is used. This allows to have several versions of the tool between different clusters.

Update the tool that a cluster uses

When a cluster is initialized with the neos init command, a dotnet-tools.json file is generated. This file contains the version of the Neos tool to use in the cluster directory.

It is recommended to keep this file on a real cluster for several reasons :

• If several developers are working on the same cluster, we are sure that all developers are using the same version.
• This allows to use different versions on different clusters.

To update the version that the cluster uses, you just have to modify the dotnet-tools.json file by indicating the version to use.

You can delete this file on a test cluster where you always want to use the latest installed version.

neos generate <(all)|client|server>

This command generates the client application and the server from the cluster metadata.

As a first argument, you have to specify what you want to generate:

• all : The client and the server (default value)
• client : Only the client
• server : Only the server

Options are available:

Option	Description
--nobuild (-nb)	Disable .NET projects compilation.
--rebuild (-rb)	Force the compilation of .NET projects even if no modified files have been detected. In addition, the client/node_modules folder is deleted so that the client application dependencies are reinstalled.
--warnaserror (-we)	Treat warnings as errors.
--build-configuration (-c) <Default|Debug|Release>	Force the configuration to be used to compile .NET projects.
--restore (-rp)	Restore referenced modules from NuGet before generation. [default: true]
--force (-f)	Force full build (no incremental build). [default: false]

If a .NET project fails to compile, each error or warning is reported individually with a message code. For more information on these diagnostics, and how to see the raw underlying build output when needed, see this article.

neos check <(all)|client|server>

This command checks that the generation is up to date.

As a first argument, you have to specify what you want to check:

• all : Client and server (default value)
• client : Only the client
• server : Only the server

If a difference is detected, the output code returned is 1 otherwise 0.

neos check-metadata

This command checks the validity of YAML metadata files, showing warnings and errors about their content.

Option	Description
--diff (-d)	Generates difference files at the root of the cluster. [default: false]
--fix (-f)	Rewrites modified YAML files and deletes obsolete YAML files. [default: false]
--check-constraints (-cc)	Runs entity constraint validation. [default: true with --file, else false]
--check-localizable-strings (-cls)	Runs partial localizable string validation. [default: true with --file, else false]
--warnaserror, --warn-as-error (-wae)	Treats warnings as errors and returns an exit code of 1 even if there are only warnings. [default: true]
--file (-fi)	Checks one metadata file by path or file name.
--format (-fo)	Applies only to auto-formattable metadata contents: XML UI templates and embedded C# code. The check computes the expected formatted content. Without --fix, a warning is reported when the current content differs. With --fix, the file is updated to match the expected formatted content. Without a value, --format means all; supported values are all, template-values, and csharp-values.
--ignore-module-dependencies (-imd)	Ignores modules located under modules/dependencies during the metadata check. [default: false]

For more information, see this article.

neos update-dbobjects

This command updates the database objects system table ($NeosObject) from the current database system catalog.

The database migration is now based on this table to select the objects eligible for updating. This command therefore synchronizes the data to be sure that the modifications of the Neos schema will be correctly taken into account.

Note

This command MUST BE run to update the system table on an existing database containing exclusively objects owned to the Neos application. Otherwise, the migration result may be unpredictable and contain errors.

Warning

This command MUST NOT BE run to update the system table on an existing database containing objects not owned by the Neos application. Otherwise, these objects will be deleted during the next migration.

neos migrate-metadata

This command migrates the cluster metadata.
It needs to be called only when an error message indicates that the metadata format has changed when generating the application after installing a new version of Neos.

neos run

This command runs the cluster application (client and server) in development mode.

Options are available:

Option	Description
--build-configuration (-c)	Set this option to force the configuration for building dotnet server projects. [default: Default]
--webserver (-ws)	Set this option to override the default web server (HttpSys or Kestrel). [default: HttpSys]
--urls (-u)	Set this option to override the default URL (URLs must be separated by a semicolon).
--launch-browser (-lb)	Set this option to launch the browser (only applicable if the client is started by the command)
--backend-only (-bo)	Set this option to start only the backend server. [default: False]
--reporting (-r)	Set this option to start reporting server. [default: False]. When the reporting server is not started at launch, it is started on first client request (*) see remark below.
--studio (-s)	Set this option to start or not Neos Studio. [default: True]
--delay-before-webapi (-dw)	Set this option to add a delay before the http request is transmitted from the web API to the backend server.
--multitenant (-mt)	Set this option to start in multitenant mode. [default: False]
--license-management (-l)	Set this option to start the License Management cluster. [default: False]
--task-scheduler (-ts)	Set this option to start the Task Scheduler cluster. [default: False]
--neos-ai (-i)	Set this option to start the Neos AI cluster. [default: False]
--allow-data-loss (-dl)	Set this option to drop/delete obsolete database objects. [default: False]
--force-migration (-fm)	Set this option to force migration even if schema version has no changed. [default: False]
--automatic-migration (-am)	Set this option to migrate database at backend startup in mono-tenant mode. [default: True]
--force-start (-fs)	Set this option to force the backend to start even if database migration failed. [default: False]
--dapr (-dp)	Set this option to start in Dapr mode. [default: True]
--client-timeout (-t)	Set this option to specify the client timeout in seconds. [default: 120]

(*) NOTE: The reporting server auto-start feature does not apply to generation requests initiated by business assemblies (IReportGenerator). Only for requests initiated from the client browser (ExecuteReportAsync or ShowReportAsync).

neos build <(all)|client|server>

This command builds the client application and the server for production (Release environment).

As a first argument, you have to specify what you want to generate:

• all : The client and the server (default value)
• client : Only the client
• server : Only the server

neos restore

This command restores referenced modules from a NuGet source.

For more information, see this article.

neos update-modules

This command updates the cluster's referenced modules (ReferencedModules) to their latest published version, reusing the same NuGet resolution mechanism as neos restore — no separate feed or credential configuration is needed.

By default, every module declared in ReferencedModules is considered; pass one or more module names as arguments to restrict the scope. A module referenced by a local path (rather than a version) is skipped.

Options are available:

Option	Description
--patch-only	Restricts the update to the latest published patch of each considered module's currently used major and minor version, instead of its latest published version overall. [default: false]
--include-transitive	Also resolves modules that are only referenced transitively through another module's NuGet graph, adding each one as a new ReferencedModules entry pinned to its latest version. Reserved for test/audit pipelines (e.g. hardening); do not use for local development. [default: false]

For each considered module with a newer version available, ReferencedModules is updated accordingly (run neos restore afterward to actually download the new version). If resolution fails for a module — for example a transient issue on a NuGet feed — the failure is logged and that module is skipped without failing the command; only a failure to persist the updated ReferencedModules is fatal.

Warning

--include-transitive deliberately breaks the rule that a transitive dependency is never turned into an explicit reference: it is meant for a test/audit pipeline that needs every dependency actually pulled in — direct or transitive — bumped and visible, not for everyday development. Using it locally adds pins to ReferencedModules that normal restore/build work does not need, and that later drift out of sync with the modules' own dependency graphs.

Examples :

# Update every referenced module to its latest published version
neos update-modules

# Update only ModuleA and ModuleB
neos update-modules ModuleA ModuleB

# Restrict the update to the latest patch of each module's current major and minor version
neos update-modules --patch-only

# Pipeline/audit usage : also pin modules only referenced transitively
neos update-modules --patch-only --include-transitive

neos pack

This command creates a NuGet package from a module.

For more information, see this article.

Options are available:

Option	Description
--output (-o)	Full name of package file or directory in which package is to be generated.

neos pack-cluster

This command creates a NuGet package from the binaries of a cluster. neos build have to been called first to generate the binaries. The NuGet package contains all the cluster configuration files.

Options are available:

Option	Description
--output (-o)	Full name of package file or directory in which package is to be generated.

Warning

This command is used internally by the Neos team, any other use is not recommended for the moment.

neos install-cluster

This command installs an optional cluster from a NuGet package. neos setup have to been called first to initialize the NuGet source. It can currently be used with the following clusters :

• TaskScheduler
• LicenseManagement
• NeosAI

Options are available:

Option	Description
--version (-v)	Version of the cluster to install (if not specified, the neos version is used).

neos upgrade-cluster

This command upgrades an optional cluster from a NuGet package. The command throws an error if the cluster is not already installed. neos setup have to been called first to initialize the NuGet source.

Options are available:

Option	Description
--version (-v)	Version of the cluster to install (if not specified, the neos version is used).

neos uninstall-cluster

This command uninstalls an optional cluster installed with neos install-cluster or neos upgrade-cluster.

neos upgrade-ai-test

This command upgrades the AI test project of your cluster. Must be used after upgrading your cluster to a new version of Neos. This is required to update the test project with the installed version of Neos.
See this article for more information.

neos create-ui-tests-project

This command creates a Visual Studio project named GroupeIsa.Neos.[ModuleName].Tests.EndToEndTests.[FeatureGroupName].csproj in the folder [ModuleName]/endToEndTests/[FeatureGroupName]. This project is added to the Visual Studio ui tests solution of the module (GroupeIsa.Neos.[ModuleName].Tests.EndToEndTests.slnx in the folder [ModuleName]/endToEndTests).

Required options :

Option	Description
--feature-group (-f)	The feature group to which the UI tests belongs.
--module (-m)	The module to which the feature grou belongs.

Example :

neos create-ui-tests-project --module Sales --feature-group ShoppingCart

neos agent <install|uninstall>

This command installs or uninstalls the global Neos Copilot agent and its skill bundle for AI coding assistants. The agent and skills are generated for the current Neos version and written to the user profile of the targeted host(s).

Two hosts are supported:

Host	Agent file	Skills directory
GitHub Copilot	~/.copilot/agents/neos-copilot-<version>.agent.md	~/.copilot/skills/neos-*-<version>
Claude	~/.claude/agents/neos-copilot-<version>.md	~/.claude/skills/neos-*-<version>

<version> is the major Neos version with a hyphen instead of a dot (for example 3-2), because Claude does not allow dots in agent and skill names.

neos agent install

Installs or updates the agent and its skills. Any existing installation for the same version is rebuilt from a clean state, and legacy installations that used a dotted version name (for example neos-copilot-3.2) are purged to avoid duplicates. By default only the Claude-format agent is installed, because VS Code reads it directly for both Claude Code and GitHub Copilot sessions; a default install also purges any Copilot-format installation left by an older Neos version, so upgrading removes the duplicate automatically.

Options are available:

Option	Description
--target (-t)	Target host: copilot, claude, or all. Defaults to claude — VS Code reads the Claude-format agent directly, so all/copilot are opt-in.

neos agent uninstall

Uninstalls the agent and its skills. Both the current and legacy (dotted) layouts are removed for the targeted version.

Options are available:

Option	Description
--target (-t)	Target host: copilot, claude, or all. Defaults to all.
--version (-v)	Major version to uninstall (for example 3.1). Defaults to the current Neos version; use it to remove agent installations left by older versions.

Examples :

# Install for every supported host (default)
neos agent install

# Install for Claude only
neos agent install --target claude

# Uninstall an old version left by a previous Neos version, from GitHub Copilot only
neos agent uninstall --version 3.1 --target copilot

neos agent <install-hooks|uninstall-hooks>

These commands install or uninstall the Neos Copilot agent hooks for AI coding assistants. The hooks are written in the current directory (so they are version-controlled with that workspace), without requiring it to be a Neos cluster. Run them at the root of a multi-cluster repository to cover every cluster in its sub-folders: the runtime handler resolves the cluster per edited file, so a single installation at the repository root protects all of them.

Two hooks are installed per host:

• A pre-tool-use hook that blocks the agent from writing into the generated server/ and client/ directories. These are regenerated from metadata, so any manual change there would be lost; the agent must edit the source metadata under modules/<module>/metadata/... and run neos generate instead. The block is hard. Both hosts use the same hookSpecificOutput deny JSON, but the transport differs: Claude Code blocks on exit code 2 with the reason on standard error, while GitHub Copilot CLI honors the deny decision in that JSON on standard output ({"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny",...}}) with exit code 0.
• A post-tool-use hook that, right after a metadata YAML file (modules/<module>/metadata/<type>/*.yml or modules/<module>/metadata/<type>/<language>/*.yml) is created or updated, runs check-metadata --file <file> -cc --fix --format on it and feeds the result back to the agent.

Scope: the hooks cover the agents' file-editing tools (Write/Edit/MultiEdit/NotebookEdit on Claude; apply_patch/create_file/str_replace/insert/edit/create/write on Copilot). Writes performed through a shell tool (e.g. Claude's Bash: redirection, sed, mv…) are not intercepted, by design: reliably extracting target paths from an arbitrary shell command is error-prone and would cause false positives (a grep/cat/echo merely mentioning the path would be blocked). The agent guidance still instructs the agent never to modify generated output.

The hook configuration is written to:

Host	Hook configuration file
GitHub Copilot	<dir>/.github/hooks/neos-copilot-hooks.json
Claude	<dir>/.claude/settings.json

where <dir> is the directory the command was run from (the current directory).

For Claude, only the Neos-managed entries are added to (or removed from) settings.json; any other configuration in that file is preserved.

Both hooks delegate to the internal neos agent run-hook handler, which reads the host payload from standard input, so all the logic lives in the Neos tool itself (no external shell script is required). The configured command is prefixed with the [json-logs] directive: this keeps the invocation silent (no banner or log on standard output) even when the neos resolved from PATH is an older global tool that redirects to the workspace's pinned version, so the hook's JSON output is never corrupted. It does require a neos reachable from the working directory (global tool, repository build, or local dotnet-tools.json) that supports run-hook.

neos agent install-hooks

Installs or updates the hooks in the current directory. The operation is idempotent: a previous Neos hook installation is replaced rather than duplicated.

Option	Description
--target (-t)	Target host: copilot, claude, or all. Defaults to all (installs for every host).

neos agent uninstall-hooks

Removes the Neos hooks from the current directory.

Option	Description
--target (-t)	Target host: copilot, claude, or all. Defaults to all.

Examples :

# Install the hooks for every supported host (run from the repo root or a cluster)
neos agent install-hooks

# Install the hooks for Claude only
neos agent install-hooks --target claude

# Remove the hooks for every host
neos agent uninstall-hooks

neos dependencies <usages|usages-by-type|unused|accessibility-suggestions|set-accessibility>

This command group brings the dependency analysis of Neos Studio (the Tools dependency viewer) to the command line. It analyzes the cluster in the current directory, so run it from a cluster root (like check-metadata or generate). Every command prints a YAML document on standard output, so the result is deterministic and easy to consume from a pipeline or an AI coding agent.

Two main use cases:

• Pipeline control: fail a build when unused (dead) elements exist in a cluster (unused --fail-on-found).
• Deterministic introspection: list the elements that use a given element, or the elements of a given type, for scripts and AI coding agents.

An element is identified by its metadata entity type (for example Entity, UIView, ServerMethod, DataObject) and its name (dot-separated for child elements, for example Customer or Customer.Address).

Exit codes: 0 on success, 1 on error (invalid arguments, element not found, etc.), and 2 for unused --fail-on-found when at least one unused element exists.

The YAML output is a dependency tree. For example, neos dependencies usages --type Entity --name Customer prints:

name: Customer
type: Entity
moduleName: Sales
accessibility: DomainAndApplication
children:
- name: CustomerView
  type: EntityView
  moduleName: Sales
  paths:
  - modules/Sales/metadata/EntityViews/CustomerView.yml
- name: GetCustomer
  type: ServerMethod
  moduleName: Sales

usages and set-accessibility operate on one element, so they emit a single element object (as above). The bulk commands — usages-by-type, unused, and accessibility-suggestions — emit a top-level YAML array of elements instead.

neos dependencies usages

Lists every element that uses the given element.

Option	Description
--type (-t)	The metadata entity type of the element (for example Entity). Required.
--name (-n)	The element name (dot-separated, for example Customer.Address). Required.
--load-all	Recursively load the whole dependency tree. [default: false]

neos dependencies usages-by-type

Lists the usages of every element of a given type (or of all analyzable types when --type is omitted).

Option	Description
--type (-t)	The metadata entity type to analyze. Omit to analyze all types.
--load-all	Recursively load the whole dependency tree. [default: false]

neos dependencies unused

Lists the defined-but-unused elements (potential dead code). Manual UsedBy references are honored, so an element explicitly marked as used is not reported.

Option	Description
--fail-on-found	Return a non-zero exit code (2) when at least one unused element is found. [default: false]

Note

Use --fail-on-found in a pipeline to break the build on dead code. The command returns 2 when unused elements exist, 0 when none are found, and 1 on error.

neos dependencies accessibility-suggestions

Lists the elements whose accessibility (layer / scope) could be changed, with the suggested target accessibility and the instructions to apply it.

neos dependencies set-accessibility

Applies an accessibility change to an element and propagates the resulting renames across all of its references. On success it prints the updated element's dependency tree as YAML, consistent with the other sub-commands.

Option	Description
--type (-t)	The metadata entity type of the element. Required.
--name (-n)	The element name. Required.
--to	Target accessibility. Required, and must be a persistable value: Application, DomainAndApplication, Frontend, ApplicationAndFrontend, All. (None and Domain are rejected — Domain is stored identically to DomainAndApplication and would not round-trip.)

Examples :

# Who uses the "Customer" entity?
neos dependencies usages --type Entity --name Customer

# Usages of every server method, with the full dependency tree
neos dependencies usages-by-type --type ServerMethod --load-all

# List the dead code in the current cluster
neos dependencies unused

# Fail the pipeline when any unused element exists (exit code 2)
neos dependencies unused --fail-on-found

# Suggested accessibility changes
neos dependencies accessibility-suggestions

# Move a UI view to the frontend layer and propagate the change across references
neos dependencies set-accessibility --type UIView --name CustomerEditor --to Frontend