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

# Command-Line Administration

> CLI tools for managing Gitea from the command line

## Overview

Gitea provides a comprehensive command-line interface for administrative tasks. All commands are accessed through the `gitea` binary.

## Command Structure

```bash theme={null}
gitea [command] [subcommand] [options]
```

View all available commands:

```bash theme={null}
gitea --help
```

## Admin Commands

The `admin` command provides administrative operations (see `cmd/admin.go:22-89`).

```bash theme={null}
gitea admin --help
```

### User Management

All user management commands are under `gitea admin user` (see `cmd/admin_user.go`).

#### Create User

Create a new user account (see `cmd/admin_user_create.go:22-101`):

```bash theme={null}
gitea admin user create \
  --username johndoe \
  --email john@example.com \
  --password secretpassword
```

**Options:**

<ParamField path="--username" type="string" required>
  Username for the new account
</ParamField>

<ParamField path="--email" type="string" required>
  Email address for the new account
</ParamField>

<ParamField path="--password" type="string">
  Password for the account (required unless using `--random-password`)
</ParamField>

<ParamField path="--random-password" type="boolean">
  Generate a random password
</ParamField>

<ParamField path="--random-password-length" type="number" default="12">
  Length of the generated random password
</ParamField>

<ParamField path="--admin" type="boolean">
  Create user as administrator
</ParamField>

<ParamField path="--must-change-password" type="boolean" default="true">
  Require password change on first login (default for all users except the first)
</ParamField>

<ParamField path="--restricted" type="boolean">
  Create as a restricted user account
</ParamField>

<ParamField path="--user-type" type="string" default="individual">
  User type: `individual` or `bot`
</ParamField>

<ParamField path="--fullname" type="string">
  Full, human-readable name of the user
</ParamField>

<ParamField path="--access-token" type="boolean">
  Generate an access token for the user
</ParamField>

<ParamField path="--access-token-name" type="string" default="gitea-admin">
  Name for the generated access token
</ParamField>

<ParamField path="--access-token-scopes" type="string" default="all">
  Comma-separated scopes: `all`, `read:user`, `write:repository`, etc.
</ParamField>

**Examples:**

<CodeGroup>
  ```bash Create Admin User theme={null}
  gitea admin user create \
    --username admin \
    --email admin@example.com \
    --password AdminPassword123 \
    --admin
  ```

  ```bash Create User with Random Password theme={null}
  gitea admin user create \
    --username developer \
    --email dev@example.com \
    --random-password \
    --random-password-length 16
  ```

  ```bash Create Bot User theme={null}
  gitea admin user create \
    --username ci-bot \
    --email bot@example.com \
    --user-type bot \
    --access-token \
    --access-token-scopes "write:repository,read:organization"
  ```
</CodeGroup>

#### List Users

```bash theme={null}
gitea admin user list
```

Displays all registered users.

#### Change Password

```bash theme={null}
gitea admin user change-password \
  --username johndoe \
  --password newpassword
```

#### Delete User

```bash theme={null}
gitea admin user delete --username johndoe
```

Options:

* `--id` - Delete by user ID instead of username
* `--purge` - Purge user data completely

#### Generate Access Token

```bash theme={null}
gitea admin user generate-access-token \
  --username johndoe \
  --token-name "API Token" \
  --scopes "write:repository,read:user"
```

#### Force Password Change

```bash theme={null}
gitea admin user must-change-password \
  --username johndoe \
  --yes
```

### Authentication Sources

Manage external authentication sources via CLI (see `cmd/admin_auth.go`).

#### List Authentication Sources

```bash theme={null}
gitea admin auth list
```

Outputs a table showing:

* ID
* Name
* Type (LDAP, OAuth2, SMTP, etc.)
* Enabled status

#### Add LDAP Authentication

See [Authentication Documentation](/admin/authentication) for detailed LDAP configuration.

```bash theme={null}
gitea admin auth add-ldap \
  --name "Corporate LDAP" \
  --security-protocol ldaps \
  --host ldap.example.com \
  --port 636 \
  --bind-dn "cn=gitea,ou=service,dc=example,dc=com" \
  --bind-password "service-password" \
  --user-search-base "ou=users,dc=example,dc=com" \
  --user-filter "(uid=%s)" \
  --email-attribute mail
```

#### Add OAuth2 Authentication

```bash theme={null}
gitea admin auth add-oauth \
  --name "GitHub" \
  --provider github \
  --key "client-id" \
  --secret "client-secret"
```

#### Add SMTP Authentication

```bash theme={null}
gitea admin auth add-smtp \
  --name "Corporate Email" \
  --host mail.example.com \
  --port 587 \
  --auth-type PLAIN
```

#### Update Authentication Source

```bash theme={null}
gitea admin auth update-ldap --id 1 --port 636
```

#### Delete Authentication Source

```bash theme={null}
gitea admin auth delete --id 1
```

### Repository Operations

#### Sync Repository Releases

Synchronize repository releases with Git tags (see `cmd/admin.go:98-157`):

```bash theme={null}
gitea admin repo-sync-releases
```

This command:

* Scans all repositories
* Compares tags with releases
* Creates releases for tags without corresponding releases

### Regenerate Data

Regenerate Git hooks and SSH keys (see `cmd/admin_regenerate.go`).

#### Regenerate Git Hooks

```bash theme={null}
gitea admin regenerate hooks
```

Regenerates Git hooks for all repositories. Useful after:

* Gitea upgrades
* Manual hook modifications
* Repository corruption

#### Regenerate SSH Keys

```bash theme={null}
gitea admin regenerate keys
```

Rebuilds the `authorized_keys` file from the database.

### Send Mail to All Users

Send an administrative message to all users:

```bash theme={null}
gitea admin sendmail \
  --title "Maintenance Notice" \
  --content "System maintenance scheduled for Saturday" \
  --force
```

## Backup and Restore

See [Backup and Restore Documentation](/admin/backup-restore) for complete details.

### Create Backup

```bash theme={null}
gitea dump --file backup.zip
```

### Restore Repository

```bash theme={null}
gitea restore-repo \
  --repo_dir /backup/repos/owner/repo.git \
  --owner_name owner \
  --repo_name repo
```

## Database Operations

### Run Migrations

```bash theme={null}
gitea migrate
```

Manually run database migrations.

### Migrate Storage

Migrate storage between different backends:

```bash theme={null}
gitea migrate-storage \
  --type lfs \
  --storage local-lfs
```

Supported types:

* `lfs` - LFS objects
* `avatars` - User avatars
* `attachments` - Issue/comment attachments
* `packages` - Package registry data
* `repo-avatars` - Repository avatars

## Configuration Management

### View Configuration

```bash theme={null}
gitea manager show-config
```

Displays the effective configuration including:

* Default values
* app.ini overrides
* Environment variable overrides

### Logging Management

```bash theme={null}
# Add logger
gitea manager logging add-logger \
  --name console \
  --level Info

# Remove logger
gitea manager logging remove-logger --name console

# Pause logging
gitea manager logging pause

# Resume logging
gitea manager logging resume
```

## Doctor Commands

Diagnostic and repair tools:

```bash theme={null}
gitea doctor check --all
```

### Available Checks

* `paths` - Check path configurations
* `db-version` - Verify database version
* `db-consistency` - Check database consistency
* `repo-integrity` - Verify repository integrity
* `check-hooks` - Validate Git hooks
* `check-db-consistency` - Advanced database checks
* `authorized-keys` - Check SSH authorized\_keys file
* `config` - Validate configuration

### Run Specific Check

```bash theme={null}
gitea doctor check --run db-version
```

### Repair Mode

```bash theme={null}
gitea doctor check --all --fix
```

### Convert Database Encoding

```bash theme={null}
gitea doctor convert --from utf8 --to utf8mb4
```

## Certificate Management

### Generate Self-Signed Certificate

```bash theme={null}
gitea cert \
  --host localhost,example.com \
  --ca \
  --duration 8760h
```

Outputs:

* `cert.pem` - Certificate
* `key.pem` - Private key

## Web Server

### Start Gitea

```bash theme={null}
gitea web
```

Options:

* `--port` - Override HTTP port
* `--pid` - Write PID to file
* `--config` - Specify config file location

## Generate Commands

### Generate Secret Keys

```bash theme={null}
# Generate SECRET_KEY
gitea generate secret SECRET_KEY

# Generate INTERNAL_TOKEN
gitea generate secret INTERNAL_TOKEN

# Generate LFS_JWT_SECRET
gitea generate secret LFS_JWT_SECRET

# Generate JWT_SECRET
gitea generate secret JWT_SECRET
```

## Hook Commands

Internal Git hook commands (used by Git, not for manual execution):

```bash theme={null}
gitea hook --config /path/to/app.ini update
gitea hook --config /path/to/app.ini pre-receive
gitea hook --config /path/to/app.ini post-receive
```

## Service Commands

### Manager Commands

```bash theme={null}
# Shutdown server gracefully
gitea manager shutdown

# Cancel shutdown
gitea manager cancel-shutdown

# Restart server
gitea manager restart

# Flush queues
gitea manager flush-queues
```

## Environment Variables

Common environment variables for CLI commands:

```bash theme={null}
# Specify config file
export GITEA_CUSTOM=/path/to/custom

# Specify work path
export GITEA_WORK_DIR=/path/to/work

# Override config values
export GITEA__database__DB_TYPE=postgres
```

## Best Practices

<Steps>
  <Step title="Use Configuration File">
    Always specify `--config` or set `GITEA_CUSTOM` to ensure commands use the correct configuration
  </Step>

  <Step title="Run as Correct User">
    Execute commands as the same user that runs Gitea (typically `git`)

    ```bash theme={null}
    sudo -u git gitea admin user list
    ```
  </Step>

  <Step title="Backup Before Major Operations">
    Always backup before running regenerate or repair commands
  </Step>

  <Step title="Test in Development">
    Test administrative commands in a development environment first
  </Step>

  <Step title="Script Repetitive Tasks">
    Create scripts for common administrative tasks
  </Step>
</Steps>

## Troubleshooting

### Command Not Found

```bash theme={null}
# Verify Gitea binary location
which gitea

# Or use full path
/usr/local/bin/gitea admin user list
```

### Permission Denied

```bash theme={null}
# Run as git user
sudo -u git gitea admin user list

# Or fix ownership
sudo chown git:git /path/to/gitea
```

### Database Connection Failed

```bash theme={null}
# Verify configuration
gitea doctor check --run config

# Check database is running
sudo systemctl status postgresql
```

## Related Resources

* [Configuration](/admin/configuration)
* [Authentication](/admin/authentication)
* [Database Setup](/admin/database)
* [Backup and Restore](/admin/backup-restore)