> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperterse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Command line reference

> Complete command and flag reference for the Hyperterse CLI.

All commands load `.env` files from the working directory when present.

```bash theme={null}
hyperterse [command] [flags]
```

<ParamField body="--version" type="boolean">
  Print the installed version and exit.
</ParamField>

## `hyperterse start`

Read config, validate the project, package tool scripts, open database connections, and start the HTTP server (MCP and optional A2A routes).

```bash theme={null}
hyperterse start [path] [flags]
```

Without arguments, loads `.hyperterse` from the current directory. A positional `path` can point to a directory containing `.hyperterse` or directly to a config file.

### Flags

<ParamField body="--port" type="string" default="">
  Server port. Overrides config and `PORT` env var.

  Short: `-p`

  Resolution order: `--port` → `server.port` → `PORT` env → `8080`
</ParamField>

<ParamField body="--log-level" type="integer" default="0">
  Log verbosity. `1` = error, `2` = warn, `3` = info, `4` = debug. Overrides config.

  Resolution order: `--verbose` (4) → `--log-level` → `server.log_level` → `3`
</ParamField>

<ParamField body="--verbose" type="boolean" default="false">
  Sets log level to `4` (debug). Overrides `--log-level`.
</ParamField>

<ParamField body="--source" type="string" default="">
  Configuration as an inline YAML string instead of reading from a file.

  Short: `-s`
</ParamField>

<ParamField body="--watch" type="boolean" default="false">
  Hot-reload on `.terse` and `.ts` file changes. Recompiles and restarts
  automatically.
</ParamField>

<ParamField body="--log-tags" type="string" default="">
  Comma-separated tag filter. Prefix a tag with `-` to exclude it.
</ParamField>

<ParamField body="--log-file" type="boolean" default="false">
  Stream logs to `/tmp/.hyperterse/logs/` in addition to stdout.
</ParamField>

### Examples

```bash theme={null}
hyperterse start
hyperterse start --watch
hyperterse start path/to/project
hyperterse start -p 9090 --verbose
```

## `hyperterse serve`

Boot from a pre-built manifest without re-parsing source files.

```bash theme={null}
hyperterse serve [manifest-or-dir] [flags]
```

Without arguments, searches for `model.bin` in the current directory. A positional argument can point to a directory containing `model.bin` or directly to a manifest file.

### Flags

<ParamField body="--port" type="string" default="">
  Server port. Overrides the value embedded in the manifest and `PORT` env var.

  Short: `-p`
</ParamField>

<ParamField body="--log-level" type="integer" default="0">
  Log verbosity. Overrides the value embedded in the manifest.
</ParamField>

<ParamField body="--verbose" type="boolean" default="false">
  Sets log level to `4` (debug).
</ParamField>

<ParamField body="--log-tags" type="string" default="">
  Comma-separated tag filter.
</ParamField>

<ParamField body="--log-file" type="boolean" default="false">
  Stream logs to file.
</ParamField>

### Examples

```bash theme={null}
hyperterse serve dist/
hyperterse serve
```

## `hyperterse build`

Compile the project into a deployable output directory.

```bash theme={null}
hyperterse build [path] [flags]
```

Without arguments, loads `.hyperterse` from the current directory.

### Flags

<ParamField body="--out" type="string" default="dist">
  Output directory for build artifacts.

  Short: `-o`
</ParamField>

<ParamField body="--clean-dir" type="boolean" default="false">
  Remove the output directory before building.
</ParamField>

### Output

<Tree>
  <Tree.Folder name="dist" defaultOpen>
    <Tree.File name="hyperterse" comment="Runtime binary" />

    <Tree.File name="model.bin" comment="Serialized manifest" />

    <Tree.Folder name="build" defaultOpen>
      <Tree.File name="vendor.js" comment="Shared dependency bundle" />

      <Tree.Folder name="tools" defaultOpen>
        <Tree.Folder name="<name>" defaultOpen>
          <Tree.File name="handler.js" />

          <Tree.File name="input_transform.js" />

          <Tree.File name="output_transform.js" />
        </Tree.Folder>
      </Tree.Folder>
    </Tree.Folder>
  </Tree.Folder>
</Tree>

### Examples

```bash theme={null}
hyperterse build
hyperterse build -o release --clean-dir
hyperterse build path/to/project -o dist
```

## `hyperterse validate`

Check configuration and project structure without starting the server.

```bash theme={null}
hyperterse validate [path] [flags]
```

### Flags

<ParamField body="--source" type="string" default="">
  Configuration as an inline YAML string instead of reading from a file.

  Short: `-s`
</ParamField>

### Checks

* Root config schema compliance
* Adapter completeness (`connector` and `connection_string` required)
* Tool validity (exactly one of `use` or `handler`)
* Adapter name uniqueness
* Input type correctness
* Script file resolution
* Bundle compilation

### Exit codes

| Code | Meaning                                      |
| ---- | -------------------------------------------- |
| `0`  | Validation passed                            |
| `1`  | Validation failed — errors printed to stderr |

### Examples

```bash theme={null}
hyperterse validate
hyperterse validate path/to/project
```

## `hyperterse init`

Scaffold a new project with starter files.

```bash theme={null}
hyperterse init
```

### Created files

| Path                                        | Content                                                |
| ------------------------------------------- | ------------------------------------------------------ |
| `.hyperterse`                               | Root config with defaults                              |
| `app/tools/hello-world/config.terse`        | Hello world script-backed tool                         |
| `app/tools/hello-world/handler.ts`          | TypeScript handler                                     |
| `.agents/skills/hyperterse-docs/SKILL.md`   | Agent Skills skill pointing to docs                    |
| `.agents/skills/hyperterse-agents/SKILL.md` | Agent Skills skill for creating agents with Hyperterse |

<Note>Does not overwrite existing files.</Note>

## `hyperterse upgrade`

Upgrade the installed binary.

```bash theme={null}
hyperterse upgrade [flags]
```

### Flags

<ParamField body="--prerelease" type="boolean" default="false">
  Include pre-release versions in the upgrade check.
</ParamField>

<ParamField body="--major" type="string">
  Target a specific major version number, or `next` for the latest major.
</ParamField>

### Examples

```bash theme={null}
hyperterse upgrade
hyperterse upgrade --prerelease
hyperterse upgrade --major next
hyperterse upgrade --major 3
```

## `hyperterse completion`

Generate shell completion scripts. Hidden from default help.

```bash theme={null}
hyperterse completion [bash|zsh|fish|powershell]
```