dartvel_cli 0.13.7

CLI for dartvel v0.1 (routes + web client + backend configs)

dartvel_cli

The dartvel command for Dartvel, a full-stack application platform built around Flutter.

It is the one code generator (dartvel routes), the development server with hot reload across the Flutter app and its backend, the build for every target Dartvel supports, deployment to web hosts and app stores, and the tools around a running application: database migrations, queues, cache, logs, a task runner and a cross-platform shell.

This package is the command. The framework an application imports is dartvel_core and dartvel_flutter, or all of it at once through dartvel_dev.

Install

Install the CLI from pub.dev, or as a self-contained executable with the Dart runtime and the Rust server library linked into it, which needs neither Dart nor Flutter to run. Building an application still needs Flutter, for whichever target you are building.

From pub

With the Dart SDK installed (it ships with Flutter):

dart pub global activate dartvel_cli
dartvel --help

Activate dartvel_cli, the command. Activating dartvel_dev instead succeeds and then every run fails, because dartvel_dev is the package an application depends on, it depends on Flutter, and pub does not run a global command from a package that does. Pub puts dartvel in ~/.pub-cache/bin; add that to your PATH if your shell cannot find it.

Homebrew

brew install Danroyal001/dartvel_dev/dartvel_dev

The tap installs the same prebuilt binary. It is bumped after a release, so it can trail npm.

GitHub releases

Each release at github.com/Danroyal001/dartvel_dev/releases carries one binary per platform, with SHA256SUMS and latest.json:

Asset	Platform
dartvel-linux-amd64	Linux x64
dartvel-linux-arm64	Linux arm64
dartvel-darwin-amd64	macOS Intel
dartvel-darwin-arm64	macOS Apple silicon
dartvel-windows-amd64.exe	Windows x64

There is no Windows on ARM build; the x64 one runs under emulation.

curl -LO https://github.com/Danroyal001/dartvel_dev/releases/download/v0.11.5/dartvel-linux-amd64
mkdir -p ~/.dartvel/bin
mv dartvel-linux-amd64 ~/.dartvel/bin/dartvel
chmod +x ~/.dartvel/bin/dartvel
~/.dartvel/bin/dartvel ensure-path   # adds ~/.dartvel/bin to your PATH

For 0.11.5, only the Linux binaries are attached until the CI release workflow has run. Until then, npm on macOS or Windows fails on the download and prints the release URL. Use the per-project route below on those hosts, using Dart 3.13 or newer.

From pub, per project

With the Dart SDK installed, the CLI can run from a project's own dependencies. dartvel create already writes this:

dev_dependencies:
  dartvel_cli: ^0.11.5

dart run dartvel_cli:dartvel --help
dart run dartvel_cli:dartvel dev

The first dart run compiles the CLI, so it is slower than the binary.

dartvel --version prints the CLI version with the Dart, Flutter and Shorebird it finds, so a missing toolchain shows up before a build fails on it.

npm

npm install -g dartvel_dev      # or: npm install -g dartvel_cli
dartvel --help

npx dartvel_dev --help          # without installing

dartvel_cli on npm is an alias that forwards to dartvel_dev. The first time it runs, the launcher downloads the binary for your platform from the GitHub release of the same version, checks it against that release's SHA256SUMS, and keeps it beside the package. Node 18 or newer.

Quick start

dartvel create my_app          # alias: new
cd my_app
dartvel dev                    # generate, run the app and the backend, hot reload
dartvel build web              # production web build in build/web
dartvel deploy --target web --provider firebase-hosting

dartvel dev and dartvel build run the generator first, so you do not need to run dartvel routes yourself. Run it when you want the generated client (lib/dartvel_client/) refreshed without starting anything, for example so the analyzer sees a new page.

To add Dartvel to a Flutter project that already exists, use dartvel init rather than create. See example/README.md for a full session: a new app, a page, a data model, the dev server and a web build.

Coding agents

create and init also set the project up for whichever coding agent you open it in, from one generated block:

File	Read by
AGENTS.md	Codex, OpenCode, Devin, ChatGPT, and anything else that reads AGENTS.md
CLAUDE.md	Claude Code
GEMINI.md	Gemini CLI
AGENT.md	agents that read the singular name
CONVENTIONS.md	aider, and tools that read a conventions file
.cursorrules, .cursor/rules/dartvel.mdc	Cursor
.windsurfrules	Windsurf
.clinerules	Cline
.kiro/steering/dartvel.md	Kiro
.github/copilot-instructions.md	GitHub Copilot, and ChatGPT in a repository
.aider.conf.yml	aider, told which files to read

Codex, OpenCode and Devin get no file of their own: they read the project root's AGENTS.md, and four more copies would be four more files that can disagree with it.

Everything between <!-- dartvel:begin agents --> and <!-- dartvel:end agents --> is Dartvel's, and dartvel dev replaces it so it matches the Dartvel version installed. Everything outside the markers belongs to you and is never read again, and a file that had no block gains one below its existing text. The rules come from docs/agents/rules.md, which ships with the CLI, so a published Dartvel carries the rules that version had.

Commands

dartvel --help lists every command, and dartvel help <command> (or dartvel <command> --help) shows its options.

Projects

Command	What it does
create [dir]	Scaffold a new project. Alias new. Refuses to write over a project it did not create. Also writes the coding-agent files: AGENTS.md, CLAUDE.md, GEMINI.md, CONVENTIONS.md, the Cursor, Windsurf, Cline, Kiro and Copilot files, and .aider.conf.yml.
init	Add Dartvel to an existing project: the dependency and the dartvel: key, then the same coding-agent files. --dry-run, --yes.
doctor	Check the environment and the project. --target <t> checks one build target's toolchain.
upgrade --plan	Report what upgrading this project to this CLI's release changes. Writes nothing.
migrate-code	Rewrite deprecated Dartvel names. A dry run unless --apply.
update	Update the CLI itself. --check reports without installing.
version	Print the CLI version.
ensure-path	Add the dartvel binary's directory to your PATH.

Develop

Command	What it does
dev	Run the app, the backend and Studio with hot reload. Aliases run, start. Prints QR and pairing links for development builds and Dartvel Preview (dartvel-preview://open). Refreshes each coding-agent file's Dartvel block first, so the rules an agent reads match the version installed. --release refreshes it too.
routes	Run the generator: routes, the typed client, models, backend glue.
generate page|model|form|backend-function <name>	Write a starter file. generate --check fails when generated output is stale.
test	Run dart test or flutter test, with --watch, sharding and golden updates.
dev --release	Serve the existing production build locally on port 8080. Build first with dartvel build web or dartvel build web-server; use --host and --port to change the bind address.
inspect	Print the project graph: routes, models, functions, jobs and more. --json.
explain <code>	Explain a diagnostic such as DV-WINDOW-004, or every code in a family.
docs	Build a documentation site for the application from its project graph.
mcp	Serve the project-graph inspectors to a coding agent over MCP.
ai context|doctor|generate	AI helpers.
devtools	Generate the devtools metadata pages.

Build

Command	What it does
build [platform]	Build one target, or every target this host can build. See below.
prerender	Prerender routes to static HTML, with sitemap.xml and robots.txt.
capture	Photograph what a build rendered and fail on a blank one (pages, firefox, pty, studio, pwa-sync, verify).
artifact split|join	Split a large artifact into committable chunks, or rejoin them.
engine plan|verify	Resolve and verify a from-source Flutter engine build.
webos verify-package	Check an assembled webOS package.

Deploy and operate

Command	What it does
deploy --preview	Create or redeploy an isolated branch deployment; --from-pr N associates a pull request. Use --list, --open, --destroy or --sweep to manage it. Requires a hosting adapter; none ships yet. --logs [--follow] reports that log retrieval is not supported yet.
deploy	Ship a web build or a server (--provider), or an app to a store (--store).
key	The application key (generate, rotate, status), and credentials kept in Dartvel Cloud (cloud).
admin grant|revoke|list	Say who may open Studio on a deployed application. admin generate writes the admin pages.
updates release|patch|rollback	Over-the-air updates through Shorebird, or a patch source you host.
infra plan|provision|check	Provision and check the hosts declared under dartvel.infra.
compatibility-check	Check the build's protocol against the clients an environment still serves.
logs, traces, metrics	Read a running server's recent logs, trace spans and /metrics.
analyze performance	Performance measurements from a running application.

Data and application services

Command	What it does
db migrate|push|pull|seed	Schema migrations and seeding. migrate --plan classifies each change without applying it.
queue work|failed|retry|flush	Work and inspect job queues.
cache clear|inspect|purge|revalidate	Inspect and revalidate the cache.
privacy check|export|erase|retention	Subject paths, retention, and a subject's export or erasure.
flags list|prune	Declared feature flags, and the ones past their expiry with the code still reading them.
i18n extract|check	Collect translatable strings and check locale catalogues.
import openapi|postman	Generate models and a typed client from an OpenAPI document or a Postman export.
add <source>	Mount a Dartvel app or automatically wrap a Dart, npm, C, Rust, WebAssembly, Maven/jar, Swift/pod, OpenAPI or GraphQL source as a pinned module. PyPI, Go and .proto are planned.
modules list|manifest|pin|publish	Inspect, pin, sign and publish modules.
plugin add|list|remove	Manage Dartvel plugins.

Scripts

Command	What it does
task <name>	Run a task declared under dartvel.tasks. --list shows them.
sh <command>	Run a command with Dartvel's escaping, environment and glob handling, the same on every OS.
spec status	Summarise which parts of the specification are built.

Building

dartvel build                        # every target this host can build
dartvel build web
dartvel build web-server             # one executable: backend, web app and Studio
dartvel build android --format aab   # the App Bundle Google Play takes
dartvel build ios --format ipa       # the IPA App Store Connect takes
dartvel build android --profile development   # a build `dartvel dev` pairs with (or apps/dartvel_preview for universal preview)

--profile is development (Flutter debug, with dev-client pairing on Android, iOS, macOS, Linux and Windows; used by project builds and Dartvel Preview), profile, or release (the default).

Targets: web, web-server, android, fireos, ios, macos, windows, linux, tvos, tizen (alias tpk), sony-elinux (with --format bundle|iso|img) and webos. These are free.

Not all of these build today. web, web-server, linux, android, fireos, windows, macos and ios build and have been checked; tvos is verified for the simulator only; tizen needs Tizen Studio installed by hand; webos skips because LG's toolchain bundles a Dart too old for Dartvel. The per-target evidence is in docs/build-targets.md.

Paid targets

visionos, horizon, chrome-extension, firefox-extension, vscode, telegram, the terminal targets (linux-cli, macos-cli, windows-cli, fuchsia-cli, each also -tui) and fuchsia are included in every Dartvel Cloud plan and are not part of the free install. So are the runtime APIs that go with them: DV.Platform.telegram, Telegram sign-in and Stars, the XR runtime behind DV.Window, DVTerminalSurface and DVBrowserExtension now live in the private dartvel_runtimes_pro package. On a free install dartvel build visionos says so and exits 69; nothing is built and nothing is sent anywhere. To build one:

• on Dartvel Cloud: dartvel build visionos --cloud;
• on your machine: dartvel targets add pro, which adds the private dartvel_targets_pro package to the project as a dev dependency and dartvel_runtimes_pro as a dependency (they need the repository access a Cloud plan grants; dartvel targets add runtimes adds only the runtimes). dartvel build <target> then runs through that package. It adds build steps only: nothing from it, and no licence key, reaches the application you ship.

dartvel targets lists what this install can build. Dartvel 0.11.5 and earlier built these targets in the open and remain MIT licensed.

Build targets from a package

A target the CLI does not build itself is a DVBuildTarget from package:dartvel_cli/build_targets.dart. A package declares its targets in a dartvel_targets.yaml at its root:

executable: dartvel_targets   # bin/dartvel_targets.dart
targets: [hologram]

and its executable registers them and runs the CLI:

import 'package:dartvel_cli/build_targets.dart';

Future<void> main(List<String> arguments) =>
    dvRunWithTargets(arguments, <DVBuildTarget>[HologramTarget()]);

dartvel build hologram in a project that depends on the package finds it through .dart_tool/package_config.json and runs the build through that executable. A target either builds itself or rides a free platform's pipeline with context.buildPlatform('android', variant: DVPlatformVariant(...)), adding Flutter arguments, leaving out steps (kiosk, home widgets, purchases, the dev client) and running prepare/finish hooks around the Flutter build. A free target's name cannot be registered.

Runtimes from a package

The runtime APIs behind the paid targets (the Telegram Mini App host and its sign-in, the XR runtime behind DV.Window, the terminal surface and the browser-extension runtime) are not in the free packages either; they plug into public extension points (DVPlatformHost, DVWindowSpaceBackend, DVAttachedSurface, AuthProvider, DVStoreAdapter). A package that provides runtimes carries a dartvel_runtimes.yaml, read like dartvel_targets.yaml:

runtimes: [telegram]
client:
  import: package:acme_runtimes/acme_runtimes.dart
  install: dvInstallAcmeRuntimes      # void Function(Map<String, Object?> sections)
  terminal_surface: AcmeTerminal.attach()   # for a terminal-only build
server:
  import: package:acme_runtimes/server.dart
  auth_providers:
    telegram: acmeTelegramAuthProvider()

The generated client imports client.import and calls client.install at startup with the dartvel: sections that configure runtimes (telegram); the generated backend installs the provider named for a configured section. dartvel.telegram in pubspec.yaml with no package providing it stops generation with exit 69 and says how to get one. dartvel targets add runtimes adds the paid dartvel_runtimes_pro package as a dependency; add pro adds it with dartvel_targets_pro. A section that configures a runtime holds public metadata only: a key that reads as a secret (botToken) is refused.

A build checks host support and the tools it needs before generating anything, so it never starts something it cannot finish. Flutter has no desktop cross-compilation: Windows builds need Windows and Apple targets need macOS, and dartvel build skips what the host cannot build. Tools Dartvel can fetch unattended (embedder forks, the webOS CLI, Linux desktop dependencies) are installed under ~/.dartvel/toolchains/ after a prompt, or without one in CI; --auto-install and --no-auto-install override that. Licence-gated SDKs (Xcode, Visual Studio, the Android SDK, Tizen Studio) are never installed for you; the build prints what to install instead.

--cloud sends the build to Dartvel Cloud, which needs a paid plan and a token (--cloud-token or DARTVEL_CLOUD_TOKEN).

Android release builds

A release build of android or fireos (and of the paid horizon) is signed with your own key and is refused, before anything is generated, when there is none. Dartvel never signs a release with the debug key. Keep the key out of the repository and point at it one of two ways:

dartvel:
  android:
    signing:
      keyProperties: ../secrets/key.properties   # storeFile (relative to this file), storePassword, keyAlias, keyPassword
    internet: true           # INTERNET in the main manifest (the default)
    allowBackup: false       # the default
    cleartextHosts: []       # hosts a release may reach over plain HTTP

or the variables DARTVEL_ANDROID_KEYSTORE, DARTVEL_ANDROID_KEYSTORE_PASSWORD and DARTVEL_ANDROID_KEY_ALIAS (plus DARTVEL_ANDROID_KEY_PASSWORD when it differs), as a CI secret store sets them. android/key.properties, Flutter's own convention, is read last. The key reaches Gradle through the environment only.

The generated Android project also gets, on every build: INTERNET in the main manifest (Flutter declares it only for debug and profile), backup off with rules that stop device-to-device transfer too (with allowBackup: true the databases, the session token and the offline store are still excluded), cleartext refused through a network security config except to cleartextHosts (debug and profile also reach localhost and the emulator host), and an R8 rule keeping the dev.dartvel classes Dart calls over JNI. Debug and profile builds are otherwise unchanged.

Deploying

dartvel deploy --target web --provider vercel      # also firebase-hosting, netlify, cloudflare
dartvel deploy --target server                     # builds web-server; ship build/server yourself
dartvel deploy --functions --function-target cloud-run   # one artifact per backend function in build/deploy
dartvel deploy --store play --dry-run              # also appstore, testflight, firebase-app-distribution

--target defaults to all, which builds every platform the host can. Name the target you mean. With no --provider the command builds and stops, and you deploy from build/ yourself. Secrets declared as required for the --environment (default production) must resolve before anything ships.

Stores are declared under dartvel.deploy.stores.<store> in pubspec.yaml and deploy an artifact you built first (dartvel build android --format aab, dartvel build ios --format ipa).

Configuration

The CLI reads the dartvel: section of the project's pubspec.yaml. Every key is optional; dartvel create writes the common ones.

dartvel:
  pagesDir: lib/pages
  backendDir: lib/backend
  backendPort: 3000
  devBackendHost: http://localhost:3000
  prodBackendHost: https://api.example.com
  apiBasePath: /api
  envFiles: [.env, .env.local]
  ota: false
  transitions:
    default: fade
    durationMs: 200
    curve: easeInOut
  seo:
    siteName: My app
    defaultTitle: Welcome
    defaultDescription: A Dartvel application

Key	Default	Meaning
pagesDir	lib/pages	Where file-based pages live.
modelsDir	lib/models	Where data models live.
backendDir	lib/backend	Where backend functions live.
componentsDir, stylesDir, servicesDir	lib/components, lib/styles, lib/services	Other source folders the generator reads.
backendHost	0.0.0.0	Address the development backend binds to.
backendPort	3000	Port of the development backend.
devBackendHost	http://localhost:<backendPort>	Backend URL the app calls in development.
prodBackendHost	empty	Backend URL the app calls in a release build. A web-server build calls its own origin instead.
apiBasePath	/api	Path prefix for backend functions.
envFiles	[.env, .env.local]	Environment files loaded, in order. PUBLIC_ variables reach the client.
seo	empty	siteName, defaultTitle, defaultDescription, defaultImage, twitterHandle.
transitions	fade, 220, easeInOut	Default page transition: default, durationMs, curve.
routingNormalizeTrailingSlash	true	Treat /about/ as /about.
notFoundRedirect	empty	Where an unknown route redirects.
plugins	[]	Enabled Dartvel plugins.
ota	false	Over-the-air updates.

Other sections are read by the commands that need them, for example tasks (dartvel task), database (provider, path; used by dartvel db), deploy.stores (dartvel deploy --store), admin (enabled, path, the Studio mount, /__studio by default), terminal (link the terminal backend into desktop builds), modules, deviceProfiles and infra.

dartvel:
  tasks:
    lint: dart analyze
    gen: dartvel routes

Code generation

Dartvel has one generator and it is this CLI. dartvel routes writes the whole client under lib/dartvel_client/, including the dartvel_client.dart barrel every page imports, and dartvel dev and dartvel build run it before anything else. Output is byte-identical for identical inputs, so dartvel generate --check can fail CI when committed output is stale.

dartvel_generator's build_runner builders are retired: they still run and warn on every build, and are removed in dartvel_generator 2.0.0. Do not add build_runner to an application for Dartvel's sake. dartvel build and dartvel dev still run it, after Dartvel's own generation, when a project declares it for another package's builders.

Routes are typed. Navigate with the generated DVRoutes members rather than path strings:

context.navigateToPage(DVRoutes.about);

doctor

dartvel doctor
dartvel doctor --target tizen
dartvel doctor --target android,ios
dartvel doctor --modules

Plain doctor checks Dart, Flutter and Git, lists optional tools (Shorebird, Codemagic), checks the project (the dartvel: section, the Flutter dependency, the configured pages, backend and models folders, .env) and then prints flutter doctor. [+] passed, [!] needs attention, [-] is information: a project with no models has no models folder, and that is fine.

--target checks one embedded or TV target's toolchain (a paid target answers through its package, or says how to get it), or, for android and ios, the deep-link verification files your declared domains serve. --modules verifies every module pin against what the application grants.

Troubleshooting

dartvel publish is an unknown command. It was removed in 0.6.0. Store submission is dartvel deploy --store play|appstore|testflight|firebase-app-distribution, and a dartvel.publish: block is refused, naming where each store moved under dartvel.deploy.stores.

--release or --no-release is a usage error on build. Since 0.6.0 the mode is --profile development|profile|release. dartvel build dev-client is gone too: build --profile development for the platform instead.

dartvel create refuses with DV-ADOPT-005. The directory already holds a pubspec.yaml that Dartvel did not write. Create into a new directory, or run dartvel init to add Dartvel to that project.

flutter pub get failed during create. The scaffold is still written. Fix what pub reports (usually network or an SDK older than Dart 3.13 / Flutter 3.47) and run flutter pub get in the project.

dartvel build web exits 1 with an accessibility finding. A web build reads each page's semantics tree and fails on a page a screen reader cannot use, such as page-heading for a page with no level 1 heading. Give the page a heading (@DVPage(title: ..., showAppBar: true) makes the bar title one, or DVText(...).modifier(const DVModifier().semanticHeading(1))), or record a documented exception under dartvel.accessibility.waivers as a list of route, rule and reason. The files in build/web are already written when the audit runs. --no-prerender skips the audit along with the prerendered HTML, for a build nobody will serve.

A target is skipped. The host cannot build it, or a tool is missing. Run dartvel doctor --target <target>; the skip message names the tool.

Target of URI doesn't exist: '../dartvel_client/dartvel_client.dart'. The client has not been generated yet. Run dartvel routes.

npm says HTTP 404 fetching the binary. That release carries no binary for your platform. The error prints the release page; see the 0.6.0 note under Install.

A diagnostic code you do not recognise. dartvel explain DV-GEN-001, or a family: dartvel explain DV-KIOSK.

0.6.0 breaking changes

• dartvel publish is removed; use dartvel deploy --store. Stores are declared under dartvel.deploy.stores.
• --provider firebase is refused; Firebase Hosting is --provider firebase-hosting.
• dartvel build --profile development|profile|release replaces --release, --no-release and the old boolean --profile. build dev-client is gone.
• dartvel init adopts an existing project and is no longer an alias of create.
• dartvel create refuses to scaffold over a project it did not create.

The full list is in the changelog.

The name

dartvel on pub.dev was taken on 2026-08-06 by an unrelated package, so the published identifiers carry a suffix: dartvel_cli for this package and dartvel_dev for the umbrella on pub.dev, npm and Homebrew. The command is dartvel however you install it.

Links

• dartvel.dev
• Repository and getting started
• Build targets and their evidence
• What is built, per spec section
• Releases
• Issues