# TypeDB Admin Tool

`typedb admin` is a CLI tool bundled with every TypeDB distribution. It connects to the server’s local-only admin endpoint to inspect server status and run administrative commands such as resetting a user’s password.

The admin endpoint is a Unix domain socket on Linux and macOS, and a Named Pipe on Windows. Access is enforced by the operating system: the socket file is created with mode `0600` (owner-only) on Unix, and the Named Pipe carries a DACL that grants access only to the server’s owner, `LOCAL SYSTEM`, and `BUILTIN\Administrators` on Windows. The admin tool must run on the same host as the server.

## [](#_connect)Connect

The admin endpoint is **off by default**. Start the server with the admin endpoint enabled — see [Server configuration / Admin endpoint](../../maintenance-operation/typedb-configuration/index.md#_admin). By default, the endpoint is at `<data-directory>/admin.sock` on Linux/macOS and `\\.\pipe\typedb-admin` on Windows; both can be overridden with `server.admin.socket-path`.

Point the admin tool at that path (providing the socket path is required to choose the server to connect to):

```bash
# Linux/macOS
typedb admin --socket-path /var/lib/typedb/data/admin.sock

# Windows
typedb admin --socket-path \\.\pipe\typedb-admin
```

## [](#_modes)Modes

The admin tool supports three modes.

### [](#_interactive_repl)Interactive (REPL)

Run with no `--command` or `--script` to enter an interactive REPL.

```bash
typedb admin --socket-path /var/lib/typedb/data/admin.sock
```

The REPL prints the connected server’s distribution and version, then accepts commands one at a time. Use `help` to list available commands, and `exit` to quit.

### [](#_one_shot_commands)One-shot commands

Pass one or more `--command` (`-c`) flags to execute commands and exit. Useful in scripts and CI checks.

```bash
typedb admin --socket-path /var/lib/typedb/data/admin.sock --command "server status"
typedb admin --socket-path /var/lib/typedb/data/admin.sock -c "server version" -c "server status"
```

The exit code is non-zero if any command fails.

### [](#_script)Script

Execute a file containing one command per line and exit.

```bash
typedb admin --socket-path /var/lib/typedb/data/admin.sock --script ./admin-checks.txt
```

`--command` and `--script` cannot be combined.

## [](#_commands)Commands

 

Built-in commands

`server version`

Print the running server’s distribution name and version.

`server status`

Print every endpoint the server is serving and advertising (gRPC, HTTP, admin, monitoring).

`user reset-password <username> [<new-password>]`

Reset the password of an existing user. If the new password is omitted, the tool prompts for it interactively (no echo) or reads one line from `stdin` when not running in a TTY.

`help`

List all available commands.

`exit`

Leave the REPL.

## [](#_examples)Examples

### [](#_inspect_server_status)Inspect server status

```bash
$ typedb admin --socket-path /var/lib/typedb/data/admin.sock --command "server status"
Status: running
Serving:
  gRPC:       0.0.0.0:1729
  HTTP:       0.0.0.0:8000
  Admin:      /var/lib/typedb/data/admin.sock (Unix socket)
  Monitoring: http://127.0.0.1:4104/diagnostics (Prometheus scrape)
              http://127.0.0.1:4104/diagnostics?format=json (JSON)
```

### [](#_reset_a_users_password_interactive)Reset a user’s password (interactive)

```bash
$ typedb admin --socket-path /var/lib/typedb/data/admin.sock
admin> user reset-password admin
New password: ********
Password updated for user 'admin'.
admin> exit
```

### [](#_reset_a_users_password_non_interactive_from_a_secret_file)Reset a user’s password (non-interactive, from a secret file)

```bash
$ cat /etc/typedb/admin-new-password | typedb admin --socket-path /var/lib/typedb/data/admin.sock -c "user reset-password admin"
```

## [](#_connection_errors)Connection errors

The admin tool verifies the socket file before connecting on Unix. Common errors:

 

`[ADM1] Failed to connect to '<path>'.`

The server is not listening on the given path, or the path is for a different server instance.

`[ADM7] Admin socket '<path>' could not be inspected.`

The path does not exist or is unreadable to the user running `typedb admin`.

`[ADM8] Admin endpoint at '<path>' is not a Unix socket; refusing to connect.`

The path resolves to a regular file or directory rather than a socket. The server is either not running or wrote to the wrong path.

``[ADM9] Admin socket '<path>' has mode `<mode>``; expected `0600`.\`

The socket file’s permission bits were changed after the server created it. Restart the server to recreate the socket with the correct mode.

On Windows, access checks are performed by the kernel when opening the pipe; permission errors surface as connection failures (`[ADM1]`).

[TypeQL Syntax Checker](../typeql-check/index.md) [TypeDB MCP Server](../mcp-server/index.md)

[Edit on GitHub](https://github.com/typedb/typedb-docs/edit/3.x-development/tools/modules/ROOT/pages/admin.adoc) Edit this page on GitHub.