Configuration

utoo uses TOML-format configuration files at two levels: global and project.

Configuration Files

Global Config

Location: ~/.utoo/config.toml

Applies to all projects. Stores global preferences like registry, cache path, etc.

~/.utoo/config.toml


[values]
registry = "https://registry.npmmirror.com"
cache-dir = "~/.cache/nm"
legacy-peer-deps = true
 
[arrays]
supports-semver = [
  "https://registry.npmmirror.com",
  "!https://registry.npmjs.org",
]

Project Config

Location: .utoo.toml (project root)

Applies only to the current project. Can override [values] from the global config. Also where catalogs are defined.

.utoo.toml


[values]
registry = "https://registry.npmjs.org"
 
[catalog]
react = "^18.0.0"
typescript = "^5.0.0"
lodash = "^4.17.21"
 
[catalogs.legacy]
debug = "^3.2.7"
path-to-regexp = "^1.9.0"

File Format

Configuration files contain the following sections:

`[values]`

Key-value configuration entries. All common settings go here.

Key	Default	Description
`registry`	`https://registry.npmmirror.com`	npm registry URL
`cache-dir`	`~/.cache/nm`	Package cache directory
`legacy-peer-deps`	`true`	Enable legacy peer dependency handling, skipping peer dependency resolution
`manifests-concurrency-limit`	`64`	Max concurrent manifest fetches

Example


[values]
registry = "https://registry.npmmirror.com"
cache-dir = "~/.cache/nm"
legacy-peer-deps = true

`[arrays]`

Array-typed configuration entries. Currently used to cache semver support probe results for registries.

Example


[arrays]
supports-semver = [
  "https://registry.npmmirror.com",
  "!https://registry.npmjs.org",
]

No prefix means the registry supports semver queries
! prefix means it does not

This field is maintained automatically by utoo and typically does not need manual editing.

`[catalog]`

Only effective in project config (.utoo.toml).

Default catalog for centralizing shared dependency versions across packages in a monorepo:

.utoo.toml


[catalog]
react = "^18.0.0"
typescript = "^5.0.0"
lodash = "^4.17.21"

Reference in package.json using the catalog: protocol:

package.json


{
  "dependencies": {
    "react": "catalog:",
    "lodash": "catalog:"
  }
}

`[catalogs.<name>]`

Only effective in project config (.utoo.toml).

Named catalogs for managing multiple version strategies:

.utoo.toml


[catalogs.legacy]
debug = "^3.2.7"
path-to-regexp = "^1.9.0"
 
[catalogs.react17]
react = "^17.0.0"
react-dom = "^17.0.0"

Reference with catalog:<name>:

package.json


{
  "dependencies": {
    "debug": "catalog:legacy",
    "react": "catalog:react17"
  }
}

Priority Order

Configuration values are resolved in the following order (highest to lowest):

CLI flags (highest) — ut install --registry https://...
Environment variables — UTOO_REGISTRY=https://...
Project config — [values] in .utoo.toml
Global config (lowest) — [values] in ~/.utoo/config.toml

Catalog configuration ([catalog] / [catalogs.*]) is read only from the project config and is not inherited from the global config.

Environment Variables

Variable	Description
`UTOO_REGISTRY`	Override npm registry
`UTOO_CACHE_DIR`	Override cache directory
`CI`	Set to `1` or `true` to disable auto-update
`UTOO_FORCE_UPDATE`	Set to `1` to force an immediate update

Terminal


UTOO_REGISTRY=https://registry.npmmirror.com ut install

CLI Config Management

Read and write configuration via the ut config command:

Set

Terminal


# Set in project config (.utoo.toml)
ut config set registry https://registry.npmmirror.com
 
# Set in global config (~/.utoo/config.toml)
ut config set registry https://registry.npmmirror.com --global

Get

Terminal


ut config get registry

Delete

Terminal


ut config delete registry
ut config delete registry --global

List

Terminal


ut config list

Custom Commands

Define shortcuts for frequently used commands:

Terminal


# Set custom commands
ut config set hi.cmd "utx cowsay hi"
ut config set lint.cmd "ut run lint"
 
# Run custom commands
ut hi
ut lint

Registry Recommendations

China

Terminal


ut config set registry https://registry.npmmirror.com --global

Faster for users in China.