Configuration

utoo reads TOML configuration from two locations:

Global — ~/.utoo/config.toml, applied to every project.
Project — .utoo.toml in the project root, overrides global settings for that project.

File sections

A config file may contain any of these TOML sections:

Section	Purpose	Global	Project
`[values]`	Scalar settings (registry, cache dir, tokens, custom commands…)	✓	✓ (overrides global)
`[arrays]`	Array settings (auto-maintained, e.g. registry probe cache)	✓	✓
`[catalog]`	Default catalog for monorepo deps	—	✓
`[catalogs.<name>]`	Named catalogs	—	✓

Example of a project .utoo.toml combining everything:

.utoo.toml


[values]
registry = "https://registry.npmjs.org"
 
[catalog]
react = "^18.0.0"
typescript = "^5.0.0"
 
[catalogs.legacy]
debug = "^3.2.7"

`[values]`

Scalar key/value settings. Written with ut config set <key> <value> (add --global to target ~/.utoo/config.toml).

Key	Default	Description
`registry`	auto-selected	npm registry URL. When unset, utoo picks the fastest reachable registry at startup.
`cache-dir`	`~/.cache/nm`	Global package cache directory
`legacy-peer-deps`	`true`	Skip peer dependency inclusion during resolution
`manifests-concurrency-limit`	`64`	Max concurrent manifest fetches
`auth-token:<host>`	—	Per-registry auth token; written automatically by `ut login`
`<name>.cmd`	—	Custom command shortcut

auth-token:<host> entries are stored in the global config so they apply across projects. ut login / ut logout are the intended way to manage them.

`[arrays]`

Array-valued settings. Currently the only entry is the semver-support probe cache, which utoo maintains automatically:


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

No prefix — the registry supports semver queries (/lodash/^4).
! prefix — the registry does not.

Probe results for multiple registries coexist, so switching --registry does not trigger a re-probe.

Catalogs

[catalog] and [catalogs.<name>] define shared dependency versions for a monorepo. They are project-only and have a dedicated chapter:

→ Catalog

Priority order

When the same value comes from multiple places, the highest-priority source wins:

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

[catalog] / [catalogs.*] are not subject to this chain — they are read only from the project config.

Environment variables

utoo behavior

Variable	Description
`UTOO_REGISTRY`	Override the npm registry
`UTOO_CACHE_DIR`	Override the 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

Authentication

Variable	Description
`NPM_TOKEN`	Fallback auth token for the active registry when no `auth-token:<host>` is stored
`NODE_AUTH_TOKEN`	Same as `NPM_TOKEN`; chosen for compatibility with GitHub Actions’ `setup-node`
`GITHUB_TOKEN`	Auth token for cloning `git+https://github.com/...` dependencies — use for private repos or to lift rate limits
`GH_TOKEN`	Alias for `GITHUB_TOKEN`; either works

Token resolution order for the registry API: NPM_TOKEN → NODE_AUTH_TOKEN → auth-token:<host> in global config.

Network proxy

Variable	Description
`ALL_PROXY`	Proxy for all requests (takes precedence)
`HTTPS_PROXY`	Proxy for `https://` requests
`HTTP_PROXY`	Proxy for `http://` requests

utoo reads both upper-case and lower-case forms (https_proxy, etc.). System proxy auto-detection (macOS / Windows OS-level settings set by tools like Surge / Clash) is disabled — only explicit env vars are honored.

CLI management

Read and write [values] entries via ut config:

Set

Terminal


# Project config (.utoo.toml)
ut config set registry https://registry.npmmirror.com
 
# 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

Any [values] key ending in .cmd defines a top-level shortcut. ut <name> runs the stored command string:

Terminal


# Register shortcuts
ut config set hi.cmd "utx cowsay hi"
ut config set lint.cmd "ut run lint"
 
# Invoke them
ut hi
ut lint

Because they live in the same [values] table, --global applies: register once globally and every project can use them.

Registry recommendations

China

Terminal


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

Faster for users in China.