USING THE CLI4 MIN READ · MARKDOWN ↗

Configuration and discovery

Fields actually read from wu.config.json, ports, commands, and mounting metadata.

See versions, changes and requirements in Framework 4.0 and CLI 1.2.

Project file

Commands look for wu.config.json in the working directory. There is no global --config flag or wu config command. Paths are interpreted from the root where the CLI runs.

{
  "name": "conocimiento",
  "version": "1.1.0",
  "shell": {
    "dir": "shell",
    "framework": "astro",
    "port": 4321,
    "dev_cmd": "npx astro dev",
    "build_cmd": "npx astro build"
  },
  "apps": [
    {
      "name": "busqueda",
      "dir": "mf-busqueda",
      "framework": "react",
      "port": 5001,
      "dev_cmd": "npx vite",
      "build_cmd": "npx vite build"
    },
    {
      "name": "explorador",
      "dir": "mf-explorador",
      "framework": "vue",
      "port": 5002
    }
  ],
  "proxy": {
    "port": 3000,
    "open_browser": false,
    "/api": {
      "target": "http://127.0.0.1:8080",
      "rewrite": true,
      "cors": false
    }
  },
  "shared": ["react", "react-dom/client"],
  "security": {
    "enabled": true
  }
}

version is configuration metadata. The executable still uses the version compiled into main.zig; editing that field does not update the CLI.

Shell and applications

Field	Default value	Usage
`shell.dir`	`shell`	Host directory
`shell.framework`	`vanilla`	Selects shell handling
`shell.port`	`4321`	Process port in Vite mode
`shell.dev_cmd`	Empty string	Shell command in Vite mode
`shell.build_cmd`	Empty string	Falls back to Astro, Next, or Vite according to framework
`apps[].name`	Empty string	App identifier for the catalog
`apps[].dir`	Empty string	Local directory and override key
`apps[].framework`	`vanilla`	Compiler/template selection
`apps[].port`	`0`	App port in Vite mode
`apps[].dev_cmd`	`npx vite`	Legacy development command
`apps[].build_cmd`	`npx vite build`	Build command

The parser accepts only the fields it consumes. It does not validate a complete topology as a strict schema would: many values with the wrong type retain the default. Declare names, directories, and ports explicitly, and review the result with wu info.

Metadata reaching the browser

Field in each app	Values / meaning
`fullBleed` or `full_bleed`	Boolean allowing the shell to grant full width
`domOwnership` or `dom_ownership`	`wu`, `app`, or `light`
`nativeShadow` or `native_shadow`	Optional legacy alias; explicit ownership is preferable
`grants`	Maximum list of capabilities granted by the host
`compatibility`	`strict` or `v2`

These fields travel into the development catalog and build output. A host grant does not replace the corresponding request in wu.json. fullBleed communicates a presentation preference; the shell must consume it when laying out the container.

Proxy and ports

In native mode, port priority is wu dev --port, then proxy.port, then 3000. Browser-opening priority is --open or --no-open, then proxy.open_browser, which defaults to true.

Each proxy key starting with / defines a rule. It can be a string containing the destination origin or an object with target, rewrite, and cors. rewrite: true removes the prefix: /api/users is forwarded as /users. cors is optional.

The implemented proxy supports http:// origins; it rejects TLS/https://, credentials, and ambiguous destinations. Do not declare a URL containing paths as though it were an origin. shell and apps ports belong to Vite process mode; they do not create separate listeners in the native server.

New development and build settings

{
  "dev": { "allowedHosts": ["mi-tunel.example.com"] },
  "build": { "keepPreviousBuilds": 2 },
  "security": { "upgradeInsecureRequests": false }
}

dev.allowedHosts (allowed_hosts) extends permitted hosts for Host, CORS and WebSocket; it does not change the listening interface. build.keepPreviousBuilds (keep_previous_builds) retains hashed files from previous builds, defaulting to 2. security.upgradeInsecureRequests (upgrade_insecure_requests) explicitly sets the CSP directive; when absent, WU omits it if hsts is off or configured origins use HTTP.

Configuration reloads preserve grants, manifest mode and layout settings. Newly added apps enter the router and watcher; an unchanged save does not force a reload. Directories ./mf-a or mf-a/ normalize to mf-a.

Automatic discovery

If the file is missing, several commands inspect immediate subdirectories and recognize project and dependency signals. Only a directory named exactly shell becomes the shell. Other candidates are treated as microapps.

Discovery recognizes the imported adapter and exact dependency names: Preact is not mistaken for React, and Qwik/Stencil are detected. It sorts directories and assigns free ports from 5001 without colliding with the shell; explicit ports are respected.

Detection uses heuristics; it does not reproduce the entire template matrix or replace the intent of an explicit manifest. Malformed JSON reports an error and disables discovery to avoid operating on an accidental topology. Fix the file before continuing.

CLI 1.2.0 accepts manifest: "define" on each app and security.frameOrigins for remote iframes. Frame origins only enter frame-src; they do not enable host scripts or connections. The catalog navigation filter does not block fetch access. See remote apps and build.

Implementation references

wu-cli/src/config/config.zig
wu-cli/src/config/discovery.zig
wu-cli/src/runtime/allowed_hosts.zig
wu-cli/src/runtime/dev/config_reload.zig
wu-cli/src/runtime/handlers/proxy.zig