# chengos.sh Script Reference

> Applies to: ChengOS v0.1.0+ ｜ Last verified: 2026-08-14 ｜ Source: `deploy/chengos.sh`, `deploy/lib/release-update.sh`

`chengos.sh` is the single entry point for installing, operating, updating, and uninstalling ChengOS.
It runs as an interactive menu with no arguments, or as a non-interactive CLI with a command verb.
This page is a complete reference for every command, flag, and mode it supports.

## Bootstrap mode

When the script is run on a machine that does not already contain a ChengOS installation
(no `start.sh`, no `hybrid/`, no `deploy/`), it acts as a **bootstrap installer**:

```bash
curl -fsSL https://raw.githubusercontent.com/chengrouter/chengos/main/deploy/chengos.sh | bash
```

The bootstrap will:

1. Ask for an installation directory (default `./chengos`).
2. Look for a local release tarball in the current directory.
3. If none is found, download the latest release from GitHub.
4. Extract the package and re-launch `chengos.sh` in local mode.

You can also place a release tarball next to the script before running it — the bootstrap
detects `chengos-full-linux-amd64*.tar.gz` and uses it instead of downloading.

## Interactive menu

Running `chengos.sh` with no arguments launches a bilingual (Chinese / English) interactive menu:

```bash
./chengos.sh
```

| Option | Action |
|---|---|
| 1 | Install / Initialise Modules |
| 2 | Start Services |
| 3 | Stop Services (optionally stop databases too) |
| 4 | Restart Services |
| 5 | Update Modules (scripts, package, or both; force; low-disk) |
| 6 | Install CLI Only (local or remote) |
| 7 | Service Status (process, port, CLI status) |
| 8 | Install Command Shortcuts (`chengos` and `cheng` symlinks) |
| 9 | Uninstall / Stop Modules |
| 10 | Switch Language |
| 11 | Exit |
| 12 | Reset Login Credentials |
| 13 | Roll Back to Previous Version |

Language preference is stored in `.chengos_lang` and remembered across runs.

## Commands

All commands can be run non-interactively by passing the command verb as the first argument.

### install

```bash
./chengos.sh install --mode native --with api,ui,app,cli --db-install-mode managed-process \
    --ui-port 8080 --app-port 5055
```

| Flag | Default | Description |
|---|---|---|
| `--mode` | auto-detected | `native` or `docker` |
| `--with` | `api,ui,app,pg,redis,qdrant` | Comma-separated module list |
| `--db-install-mode` | `managed-process` | `managed-process` (no root) or `system-service` (sudo) |
| `--ui-port` | 8080 | UI server port |
| `--app-port` | 5055 | Chat app port |
| `--workspace-root` | `./workspaces` | Workspace storage path |

**Modules**: `api`, `ui`, `app`, `cli`, `redis` (Valkey), `qdrant`, `pg` (PostgreSQL).

When `chengflow/` and `chengflow-ui/` source directories exist, the installer compiles from
source instead of extracting a release archive.

### start

```bash
./chengos.sh start --mode native
```

Starts all recorded modules. The module set is read from `.chengos_modules` (written during
install) so you do not need to repeat `--with`.

### stop

```bash
./chengos.sh stop --mode native
./chengos.sh stop --mode native --with-infra
```

`--with-infra` also stops database services (PostgreSQL, Valkey, Qdrant).

### restart

```bash
./chengos.sh restart --mode native
```

Stops then starts with the recorded module set.

### status

```bash
./chengos.sh status --mode native
```

Prints installed version, latest available release, process PIDs, and port status.
**Exits non-zero when the API is not serving** — usable as a health probe in monitoring scripts.

### version

```bash
./chengos.sh version
```

Prints the bare installed version string (or `unknown`). Designed for scripting.

### update

```bash
./chengos.sh update                          # scripts + package (recommended)
./chengos.sh update --scripts-only           # scripts only
./chengos.sh update --package-only           # package only (binaries, frontends, config)
./chengos.sh update --force                  # force package update, skip version check
./chengos.sh update --low                    # low-disk mode (see below)
./chengos.sh update --to v0.2.0              # target a specific release
./chengos.sh update --package-only --force   # force package reinstall
./chengos.sh update --package-only --low     # low-disk package-only update
```

| Flag | Description |
|---|---|
| `--scripts-only` | Update only `chengos.sh`, `start.sh`, `stop.sh`, `status.sh`, `generate-env.sh` |
| `--package-only` | Update only the release package (binaries, frontends, config, skills, templates) |
| `--force` | Skip the version check; reinstall or downgrade deliberately |
| `--low` | Low-disk mode: sequential operation to minimise peak disk usage (see below) |
| `--to <version>` | Target a specific release version instead of the latest |

Updates are **upgrade-only** by default: `remote > local` must hold. Use `--force` to override.

The full update flow is described in [Upgrades & Rollback](/docs/deploy-upgrade-rollback).

### rollback

```bash
./chengos.sh rollback --mode native
```

Restores the most recent backup in `.chengos_backups/`, restarts services, and runs a health
check. The consumed backup is removed, so a second rollback walks one release further back.

### install-cli

```bash
./chengos.sh install-cli --target local --server-url http://127.0.0.1:19225
./chengos.sh install-cli --target remote --server-url https://your-server.example.com
```

Installs the `cheng` CLI binary and writes a config file pointing at the specified API server.

### reset-credentials

```bash
./chengos.sh reset-credentials
./chengos.sh reset-admin
```

Resets the login username, email, and/or password. Both aliases are equivalent.

### uninstall

```bash
./chengos.sh uninstall --mode native
```

Stops all services and removes package-owned files. Database data is preserved unless you
answer "yes" to the prompt about stopping databases.

## Low-disk mode (`--low`)

When the installation filesystem has very little free space (e.g. 1 GB), the normal update
flow can fail the space check because it needs room for the download, the extracted tree, the
backup, and a staged copy — all at once.

`--low` restructures the update into a **sequential** pipeline that minimises peak disk usage:

| Step | Normal mode | Low-disk mode |
|---|---|---|
| Space check | 4× archive size (~260 MB) | 2× archive size (~130 MB) |
| After extraction | Archive kept | Archive deleted immediately (~65 MB freed) |
| Before backup | Old backups kept (up to 3) | Old backups pruned to 1 (~400 MB freed) |
| File replacement | cp→staged, mv→retired, mv→staged→target | mv→retired, cp→target directly (no staged copy) |
| After install | Staging kept until function return | Staging cleaned before health check |
| Backup retention | Keep 3 | Keep 1 |

Rollback safety is preserved: one backup is always kept, and a failed health check still
triggers automatic restore.

```bash
./chengos.sh update --low                    # scripts + package, low-disk
./chengos.sh update --package-only --low     # package only, low-disk
```

## Environment variables

These variables control the update and script behaviour. Set them in the shell or in `.env`.

| Variable | Default | Description |
|---|---|---|
| `CHENGOS_BACKUP_KEEP` | 3 | Number of backups to retain after update |
| `CHENGOS_META_TIMEOUT` | 10 | Seconds for release metadata lookup |
| `CHENGOS_DOWNLOAD_TIMEOUT` | 1800 | Seconds for artifact download |
| `CHENGOS_HEALTH_TIMEOUT` | 90 | Seconds for post-update health check |
| `CHENGOS_REQUIRE_SIGNATURE` | auto | `auto`, `required`, or `off` |
| `CHENGOS_LOCAL_TARBALL` | — | Path to a local release tarball (overrides download) |
| `CHENGOS_UPDATE_BRANCH` | main | GitHub branch for script-only updates |
| `CHENGOS_RAW_BASE_URL` | derived from branch | Base URL for raw script downloads |

## Files and metadata

| File | Purpose |
|---|---|
| `.chengos_lang` | Language preference (`zh` or `en`) |
| `.chengos_install_mode` | Installation mode (`native` or `docker`) |
| `.chengos_version` | Installed release version |
| `.chengos_modules` | Comma-separated list of installed modules |
| `.chengos_cli_target` | CLI installation target path |
| `.chengos_docker_version` | Docker image version pin |
| `.chengos_backups/` | Versioned backup directories |

## Command shortcuts

Option 8 in the menu (or manual setup) creates two symlinks in `/usr/local/bin`:

- `chengos` → launches the management menu from any terminal.
- `cheng` → launches the CLI chat client with file-based credential storage.

## Next steps

- [Native Deployment](/docs/deploy-native) — day-to-day operations in native mode.
- [Upgrades & Rollback](/docs/deploy-upgrade-rollback) — the update flow in detail.
- [Deployment Modes](/docs/deploy-modes) — native vs Docker vs distributed.
- [Environment Variable Reference](/docs/config-env-reference) — every `.env` variable.