2017-11-27 05:44:32 +08:00
---
date: "2017-01-01T16:00:00+02:00"
title: "Usage: Command Line"
slug: "command-line"
weight: 10
2020-12-09 14:47:06 +08:00
toc: false
2017-11-27 05:44:32 +08:00
draft: false
menu:
sidebar:
parent: "usage"
name: "Command Line"
weight: 10
identifier: "command-line"
---
2020-12-08 12:52:26 +08:00
# Command Line
2017-11-27 05:44:32 +08:00
2020-12-09 14:47:06 +08:00
**Table of Contents**
2020-12-08 12:52:26 +08:00
{{< toc > }}
## Usage
2017-11-27 05:44:32 +08:00
2019-04-30 02:08:21 +08:00
`gitea [global options] command [command or global options] [arguments...]`
2017-11-27 05:44:32 +08:00
2020-12-08 12:52:26 +08:00
## Global options
2019-04-30 02:08:21 +08:00
All global options can be placed at the command level.
- `--help` , `-h` : Show help text and exit. Optional.
- `--version` , `-v` : Show version and exit. Optional. (example: `Gitea version 1.1.0+218-g7b907ed built with: bindata, sqlite` ).
2019-05-14 23:20:35 +08:00
- `--custom-path path` , `-C path` : Location of the Gitea custom folder. Optional. (default: `AppWorkPath` /custom or `$GITEA_CUSTOM` ).
- `--config path` , `-c path` : Gitea configuration file path. Optional. (default: `custom` /conf/app.ini).
- `--work-path path` , `-w path` : Gitea `AppWorkPath` . Optional. (default: LOCATION_OF_GITEA_BINARY or `$GITEA_WORK_DIR` )
NB: The defaults custom-path, config and work-path can also be
changed at build time (if preferred).
2017-11-27 05:44:32 +08:00
2020-12-08 12:52:26 +08:00
## Commands
2017-11-27 05:44:32 +08:00
2020-12-08 12:52:26 +08:00
### web
2018-01-09 06:48:42 +08:00
Starts the server:
2017-11-27 05:44:32 +08:00
- Options:
2020-12-09 14:47:06 +08:00
- `--port number` , `-p number` : Port number. Optional. (default: 3000). Overrides configuration file.
- `--install-port number` : Port number to run the install page on. Optional. (default: 3000). Overrides configuration file.
- `--pid path` , `-P path` : Pidfile path. Optional.
2017-11-27 05:44:32 +08:00
- Examples:
2020-12-09 14:47:06 +08:00
- `gitea web`
- `gitea web --port 80`
- `gitea web --config /etc/gitea.ini --pid /some/custom/gitea.pid`
2017-11-27 05:44:32 +08:00
- Notes:
2020-12-09 14:47:06 +08:00
- Gitea should not be run as root. To bind to a port below 1024, you can use setcap on
Linux: `sudo setcap 'cap_net_bind_service=+ep' /path/to/gitea` . This will need to be
redone every time you update Gitea.
2017-11-27 05:44:32 +08:00
2020-12-08 12:52:26 +08:00
### admin
2018-01-09 06:48:42 +08:00
Admin operations:
2017-11-27 05:44:32 +08:00
- Commands:
2020-12-09 14:47:06 +08:00
- `user` :
- `list` :
- Options:
- `--admin` : List only admin users. Optional.
- Description: lists all users that exist
- Examples:
- `gitea admin user list`
- `delete` :
- Options:
2020-12-17 15:57:32 +08:00
- `--email` : Email of the user to be deleted.
- `--username` : Username of user to be deleted.
- `--id` : ID of user to be deleted.
- One of `--id` , `--username` or `--email` is required. If more than one is provided then all have to match.
2020-12-09 14:47:06 +08:00
- Examples:
- `gitea admin user delete --id 1`
- `create` : - Options: - `--name value` : Username. Required. As of gitea 1.9.0, use the `--username` flag instead. - `--username value` : Username. Required. New in gitea 1.9.0. - `--password value` : Password. Required. - `--email value` : Email. Required. - `--admin` : If provided, this makes the user an admin. Optional. - `--access-token` : If provided, an access token will be created for the user. Optional. (default: false). - `--must-change-password` : If provided, the created user will be required to choose a newer password after
the initial login. Optional. (default: true). - `--random-password` : If provided, a randomly generated password will be used as the password of
the created user. The value of `--password` will be discarded. Optional. - `--random-password-length` : If provided, it will be used to configure the length of the randomly
generated password. Optional. (default: 12) - Examples: - `gitea admin user create --username myname --password asecurepassword --email me@example.com`
- `change-password` :
- Options:
- `--username value` , `-u value` : Username. Required.
- `--password value` , `-p value` : New password. Required.
- Examples:
- `gitea admin user change-password --username myname --password asecurepassword`
- `regenerate`
- Options:
- `hooks` : Regenerate git-hooks for all repositories
- `keys` : Regenerate authorized_keys file
- Examples:
- `gitea admin regenerate hooks`
- `gitea admin regenerate keys`
- `auth` :
- `list` :
- Description: lists all external authentication sources that exist
- Examples:
- `gitea admin auth list`
- `delete` :
- Options:
- `--id` : ID of source to be deleted. Required.
- Examples:
- `gitea admin auth delete --id 1`
- `add-oauth` :
- Options:
- `--name` : Application Name.
- `--provider` : OAuth2 Provider.
- `--key` : Client ID (Key).
- `--secret` : Client Secret.
- `--auto-discover-url` : OpenID Connect Auto Discovery URL (only required when using OpenID Connect as provider).
- `--use-custom-urls` : Use custom URLs for GitLab/GitHub OAuth endpoints.
- `--custom-auth-url` : Use a custom Authorization URL (option for GitLab/GitHub).
- `--custom-token-url` : Use a custom Token URL (option for GitLab/GitHub).
- `--custom-profile-url` : Use a custom Profile URL (option for GitLab/GitHub).
- `--custom-email-url` : Use a custom Email URL (option for GitHub).
- Examples:
- `gitea admin auth add-oauth --name external-github --provider github --key OBTAIN_FROM_SOURCE --secret OBTAIN_FROM_SOURCE`
- `update-oauth` :
- Options:
- `--id` : ID of source to be updated. Required.
- `--name` : Application Name.
- `--provider` : OAuth2 Provider.
- `--key` : Client ID (Key).
- `--secret` : Client Secret.
- `--auto-discover-url` : OpenID Connect Auto Discovery URL (only required when using OpenID Connect as provider).
- `--use-custom-urls` : Use custom URLs for GitLab/GitHub OAuth endpoints.
- `--custom-auth-url` : Use a custom Authorization URL (option for GitLab/GitHub).
- `--custom-token-url` : Use a custom Token URL (option for GitLab/GitHub).
- `--custom-profile-url` : Use a custom Profile URL (option for GitLab/GitHub).
- `--custom-email-url` : Use a custom Email URL (option for GitHub).
- Examples:
- `gitea admin auth update-oauth --id 1 --name external-github-updated`
- `add-ldap` : Add new LDAP (via Bind DN) authentication source
- Options:
- `--name value` : Authentication name. Required.
- `--not-active` : Deactivate the authentication source.
- `--security-protocol value` : Security protocol name. Required.
- `--skip-tls-verify` : Disable TLS verification.
- `--host value` : The address where the LDAP server can be reached. Required.
- `--port value` : The port to use when connecting to the LDAP server. Required.
- `--user-search-base value` : The LDAP base at which user accounts will be searched for. Required.
- `--user-filter value` : An LDAP filter declaring how to find the user record that is attempting to authenticate. Required.
- `--admin-filter value` : An LDAP filter specifying if a user should be given administrator privileges.
- `--restricted-filter value` : An LDAP filter specifying if a user should be given restricted status.
- `--username-attribute value` : The attribute of the user’
- `--firstname-attribute value` : The attribute of the user’ ’
- `--surname-attribute value` : The attribute of the user’ ’
- `--email-attribute value` : The attribute of the user’ ’
- `--public-ssh-key-attribute value` : The attribute of the user’ ’
- `--bind-dn value` : The DN to bind to the LDAP server with when searching for the user.
- `--bind-password value` : The password for the Bind DN, if any.
- `--attributes-in-bind` : Fetch attributes in bind DN context.
- `--synchronize-users` : Enable user synchronization.
- `--page-size value` : Search page size.
- Examples:
- `gitea admin auth add-ldap --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-search-base "ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(uid=%s))" --email-attribute mail`
- `update-ldap` : Update existing LDAP (via Bind DN) authentication source
- Options:
- `--id value` : ID of authentication source. Required.
- `--name value` : Authentication name.
- `--not-active` : Deactivate the authentication source.
- `--security-protocol value` : Security protocol name.
- `--skip-tls-verify` : Disable TLS verification.
- `--host value` : The address where the LDAP server can be reached.
- `--port value` : The port to use when connecting to the LDAP server.
- `--user-search-base value` : The LDAP base at which user accounts will be searched for.
- `--user-filter value` : An LDAP filter declaring how to find the user record that is attempting to authenticate.
- `--admin-filter value` : An LDAP filter specifying if a user should be given administrator privileges.
- `--restricted-filter value` : An LDAP filter specifying if a user should be given restricted status.
- `--username-attribute value` : The attribute of the user’
- `--firstname-attribute value` : The attribute of the user’ ’
- `--surname-attribute value` : The attribute of the user’ ’
- `--email-attribute value` : The attribute of the user’ ’
- `--public-ssh-key-attribute value` : The attribute of the user’ ’
- `--bind-dn value` : The DN to bind to the LDAP server with when searching for the user.
- `--bind-password value` : The password for the Bind DN, if any.
- `--attributes-in-bind` : Fetch attributes in bind DN context.
- `--synchronize-users` : Enable user synchronization.
- `--page-size value` : Search page size.
- Examples:
- `gitea admin auth update-ldap --id 1 --name "my ldap auth source"`
- `gitea admin auth update-ldap --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn`
- `add-ldap-simple` : Add new LDAP (simple auth) authentication source
- Options:
- `--name value` : Authentication name. Required.
- `--not-active` : Deactivate the authentication source.
- `--security-protocol value` : Security protocol name. Required.
- `--skip-tls-verify` : Disable TLS verification.
- `--host value` : The address where the LDAP server can be reached. Required.
- `--port value` : The port to use when connecting to the LDAP server. Required.
- `--user-search-base value` : The LDAP base at which user accounts will be searched for.
- `--user-filter value` : An LDAP filter declaring how to find the user record that is attempting to authenticate. Required.
- `--admin-filter value` : An LDAP filter specifying if a user should be given administrator privileges.
- `--restricted-filter value` : An LDAP filter specifying if a user should be given restricted status.
- `--username-attribute value` : The attribute of the user’
- `--firstname-attribute value` : The attribute of the user’ ’
- `--surname-attribute value` : The attribute of the user’ ’
- `--email-attribute value` : The attribute of the user’ ’
- `--public-ssh-key-attribute value` : The attribute of the user’ ’
- `--user-dn value` : The user’
- Examples:
- `gitea admin auth add-ldap-simple --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-dn "cn=%s,ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(cn=%s))" --email-attribute mail`
- `update-ldap-simple` : Update existing LDAP (simple auth) authentication source
- Options:
- `--id value` : ID of authentication source. Required.
- `--name value` : Authentication name.
- `--not-active` : Deactivate the authentication source.
- `--security-protocol value` : Security protocol name.
- `--skip-tls-verify` : Disable TLS verification.
- `--host value` : The address where the LDAP server can be reached.
- `--port value` : The port to use when connecting to the LDAP server.
- `--user-search-base value` : The LDAP base at which user accounts will be searched for.
- `--user-filter value` : An LDAP filter declaring how to find the user record that is attempting to authenticate.
- `--admin-filter value` : An LDAP filter specifying if a user should be given administrator privileges.
- `--restricted-filter value` : An LDAP filter specifying if a user should be given restricted status.
- `--username-attribute value` : The attribute of the user’
- `--firstname-attribute value` : The attribute of the user’ ’
- `--surname-attribute value` : The attribute of the user’ ’
- `--email-attribute value` : The attribute of the user’ ’
- `--public-ssh-key-attribute value` : The attribute of the user’ ’
- `--user-dn value` : The user’
- Examples:
- `gitea admin auth update-ldap-simple --id 1 --name "my ldap auth source"`
- `gitea admin auth update-ldap-simple --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn`
2017-11-27 05:44:32 +08:00
2020-12-08 12:52:26 +08:00
### cert
2018-01-09 06:48:42 +08:00
Generates a self-signed SSL certificate. Outputs to `cert.pem` and `key.pem` in the current
directory and will overwrite any existing files.
2017-11-27 05:44:32 +08:00
- Options:
2020-12-09 14:47:06 +08:00
- `--host value` : Comma seperated hostnames and ips which this certificate is valid for.
Wildcards are supported. Required.
- `--ecdsa-curve value` : ECDSA curve to use to generate a key. Optional. Valid options
are P224, P256, P384, P521.
- `--rsa-bits value` : Size of RSA key to generate. Optional. Ignored if --ecdsa-curve is
set. (default: 2048).
- `--start-date value` : Creation date. Optional. (format: `Jan 1 15:04:05 2011` ).
- `--duration value` : Duration which the certificate is valid for. Optional. (default: 8760h0m0s)
- `--ca` : If provided, this cert generates it's own certificate authority. Optional.
2017-11-27 05:44:32 +08:00
- Examples:
2020-12-09 14:47:06 +08:00
- `gitea cert --host git.example.com,example.com,www.example.com --ca`
2017-11-27 05:44:32 +08:00
2020-12-08 12:52:26 +08:00
### dump
2018-01-09 06:48:42 +08:00
Dumps all files and databases into a zip file. Outputs into a file like `gitea-dump-1482906742.zip`
in the current directory.
2017-11-27 05:44:32 +08:00
- Options:
2020-12-09 14:47:06 +08:00
- `--file name` , `-f name` : Name of the dump file with will be created. Optional. (default: gitea-dump-[timestamp].zip).
- `--tempdir path` , `-t path` : Path to the temporary directory used. Optional. (default: /tmp).
- `--skip-repository` , `-R` : Skip the repository dumping. Optional.
- `--database` , `-d` : Specify the database SQL syntax. Optional.
- `--verbose` , `-V` : If provided, shows additional details. Optional.
2017-11-27 05:44:32 +08:00
- Examples:
2020-12-09 14:47:06 +08:00
- `gitea dump`
- `gitea dump --verbose`
2018-02-19 11:23:41 +08:00
2020-12-08 12:52:26 +08:00
### generate
2018-02-19 11:23:41 +08:00
Generates random values and tokens for usage in configuration file. Useful for generating values
for automatic deployments.
- Commands:
2020-12-09 14:47:06 +08:00
- `secret` :
- Options:
- `INTERNAL_TOKEN` : Token used for an internal API call authentication.
- `JWT_SECRET` : LFS & OAUTH2 JWT authentication secret (LFS_JWT_SECRET is aliased to this option for backwards compatibility).
- `SECRET_KEY` : Global secret key.
- Examples:
- `gitea generate secret INTERNAL_TOKEN`
- `gitea generate secret JWT_SECRET`
- `gitea generate secret SECRET_KEY`
2018-11-01 21:41:07 +08:00
2020-12-08 12:52:26 +08:00
### keys
2018-11-01 21:41:07 +08:00
Provides an SSHD AuthorizedKeysCommand. Needs to be configured in the sshd config file:
```ini
...
# The value of -e and the AuthorizedKeysCommandUser should match the
# username running gitea
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /path/to/gitea keys -e git -u %u -t %t -k %k
```
The command will return the appropriate authorized_keys line for the
provided key. You should also set the value
`SSH_CREATE_AUTHORIZED_KEYS_FILE=false` in the `[server]` section of
`app.ini` .
NB: opensshd requires the gitea program to be owned by root and not
writable by group or others. The program must be specified by an absolute
path.
2019-12-17 09:49:07 +08:00
NB: Gitea must be running for this command to succeed.
2019-11-06 02:54:54 +08:00
2020-12-08 12:52:26 +08:00
### migrate
2020-12-09 14:47:06 +08:00
2019-11-06 02:54:54 +08:00
Migrates the database. This command can be used to run other commands before starting the server for the first time.
This command is idempotent.
2020-12-08 12:52:26 +08:00
### convert
2020-12-09 14:47:06 +08:00
2019-11-06 02:54:54 +08:00
Converts an existing MySQL database from utf8 to utf8mb4.
2020-01-11 22:24:57 +08:00
2020-12-08 12:52:26 +08:00
### doctor
2020-12-09 14:47:06 +08:00
2020-01-11 22:24:57 +08:00
Diagnose the problems of current gitea instance according the given configuration.
Currently there are a check list below:
- Check if OpenSSH authorized_keys file id correct
2020-12-09 14:47:06 +08:00
When your gitea instance support OpenSSH, your gitea instance binary path will be written to `authorized_keys`
when there is any public key added or changed on your gitea instance.
Sometimes if you moved or renamed your gitea binary when upgrade and you haven't run `Update the '.ssh/authorized_keys' file with Gitea SSH keys. (Not needed for the built-in SSH server.)` on your Admin Panel. Then all pull/push via SSH will not be work.
This check will help you to check if it works well.
2020-01-11 22:24:57 +08:00
2020-11-28 14:12:22 +08:00
For contributors, if you want to add more checks, you can wrie ad new function like `func(ctx *cli.Context) ([]string, error)` and
2020-01-11 22:24:57 +08:00
append it to `doctor.go` .
```go
var checklist = []check{
{
title: "Check if OpenSSH authorized_keys file id correct",
f: runDoctorLocationMoved,
},
// more checks please append here
}
```
2020-03-05 14:30:33 +08:00
This function will receive a command line context and return a list of details about the problems or error.
2020-07-06 08:07:07 +08:00
2020-12-08 12:52:26 +08:00
#### doctor recreate-table
2020-09-07 05:52:01 +08:00
Sometimes when there are migrations the old columns and default values may be left
unchanged in the database schema. This may lead to warning such as:
```
2020/08/02 11:32:29 ...rm/session_schema.go:360:Sync2() [W] Table user Column keep_activity_private db default is , struct default is 0
```
You can cause Gitea to recreate these tables and copy the old data into the new table
with the defaults set appropriately by using:
```
gitea doctor recreate-table user
```
You can ask gitea to recreate multiple tables using:
```
gitea doctor recreate-table table1 table2 ...
```
And if you would like Gitea to recreate all tables simply call:
```
gitea doctor recreate-table
```
It is highly recommended to back-up your database before running these commands.
2020-12-08 12:52:26 +08:00
### manager
2020-07-06 08:07:07 +08:00
Manage running server operations:
- Commands:
2020-12-09 14:47:06 +08:00
- `shutdown` : Gracefully shutdown the running process
- `restart` : Gracefully restart the running process - (not implemented for windows servers)
- `flush-queues` : Flush queues in the running process
2020-07-06 08:07:07 +08:00
- Options:
- `--timeout value` : Timeout for the flushing process (default: 1m0s)
- `--non-blocking` : Set to true to not wait for flush to complete before returning
2020-12-09 14:47:06 +08:00
- `logging` : Adjust logging commands
2020-07-06 08:07:07 +08:00
- Commands:
2020-12-09 14:47:06 +08:00
- `pause` : Pause logging
2020-07-06 08:07:07 +08:00
- Notes:
- The logging level will be raised to INFO temporarily if it is below this level.
- Gitea will buffer logs up to a certain point and will drop them after that point.
2020-12-09 14:47:06 +08:00
- `resume` : Resume logging
2020-07-06 08:07:07 +08:00
- `release-and-reopen` : Cause Gitea to release and re-open files and connections used for logging (Equivalent to sending SIGUSR1 to Gitea.)
- `remove name` : Remove the named logger
- Options:
- `--group group` , `-g group` : Set the group to remove the sublogger from. (defaults to `default` )
2020-12-09 14:47:06 +08:00
- `add` : Add a logger
2020-07-06 08:07:07 +08:00
- Commands:
- `console` : Add a console logger
- Options:
- `--group value` , `-g value` : Group to add logger to - will default to "default"
- `--name value` , `-n value` : Name of the new logger - will default to mode
- `--level value` , `-l value` : Logging level for the new logger
- `--stacktrace-level value` , `-L value` : Stacktrace logging level
- `--flags value` , `-F value` : Flags for the logger
- `--expression value` , `-e value` : Matching expression for the logger
- `--prefix value` , `-p value` : Prefix for the logger
- `--color` : Use color in the logs
- `--stderr` : Output console logs to stderr - only relevant for console
- `file` : Add a file logger
- Options:
- `--group value` , `-g value` : Group to add logger to - will default to "default"
2020-12-09 14:47:06 +08:00
- `--name value` , `-n value` : Name of the new logger - will default to mode
2020-07-06 08:07:07 +08:00
- `--level value` , `-l value` : Logging level for the new logger
- `--stacktrace-level value` , `-L value` : Stacktrace logging level
- `--flags value` , `-F value` : Flags for the logger
- `--expression value` , `-e value` : Matching expression for the logger
- `--prefix value` , `-p value` : Prefix for the logger
- `--color` : Use color in the logs
2020-11-28 14:12:22 +08:00
- `--filename value` , `-f value` : Filename for the logger -
2020-07-06 08:07:07 +08:00
- `--rotate` , `-r` : Rotate logs
- `--max-size value` , `-s value` : Maximum size in bytes before rotation
- `--daily` , `-d` : Rotate logs daily
- `--max-days value` , `-D value` : Maximum number of daily logs to keep
- `--compress` , `-z` : Compress rotated logs
- `--compression-level value` , `-Z value` : Compression level to use
- `conn` : Add a network connection logger
- Options:
- `--group value` , `-g value` : Group to add logger to - will default to "default"
2020-12-09 14:47:06 +08:00
- `--name value` , `-n value` : Name of the new logger - will default to mode
2020-07-06 08:07:07 +08:00
- `--level value` , `-l value` : Logging level for the new logger
- `--stacktrace-level value` , `-L value` : Stacktrace logging level
- `--flags value` , `-F value` : Flags for the logger
- `--expression value` , `-e value` : Matching expression for the logger
- `--prefix value` , `-p value` : Prefix for the logger
- `--color` : Use color in the logs
- `--reconnect-on-message` , `-R` : Reconnect to host for every message
- `--reconnect` , `-r` : Reconnect to host when connection is dropped
- `--protocol value` , `-P value` : Set protocol to use: tcp, unix, or udp (defaults to tcp)
- `--address value` , `-a value` : Host address and port to connect to (defaults to :7020)
- `smtp` : Add an SMTP logger
- Options:
- `--group value` , `-g value` : Group to add logger to - will default to "default"
- `--name value` , `-n value` : Name of the new logger - will default to mode
- `--level value` , `-l value` : Logging level for the new logger
- `--stacktrace-level value` , `-L value` : Stacktrace logging level
- `--flags value` , `-F value` : Flags for the logger
- `--expression value` , `-e value` : Matching expression for the logger
- `--prefix value` , `-p value` : Prefix for the logger
- `--color` : Use color in the logs
- `--username value` , `-u value` : Mail server username
- `--password value` , `-P value` : Mail server password
- `--host value` , `-H value` : Mail server host (defaults to: 127.0.0.1:25)
- `--send-to value` , `-s value` : Email address(es) to send to
- `--subject value` , `-S value` : Subject header of sent emails
