2017-11-26 16:44:32 -05:00
---
date: "2017-01-01T16:00:00+02:00"
2023-04-06 05:06:32 -04:00
title: "Gitea Command Line"
2017-11-26 16:44:32 -05:00
slug: "command-line"
2023-07-26 00:53:13 -04:00
sidebar_position: 1
2020-12-09 01:47:06 -05:00
toc: false
2017-11-26 16:44:32 -05:00
draft: false
Refactor docs (#23752)
This was intended to be a small followup for
https://github.com/go-gitea/gitea/pull/23712, but...here we are.
1. Our docs currently use `slug` as the entire URL, which makes
refactoring tricky (see https://github.com/go-gitea/gitea/pull/23712).
Instead, this PR attempts to make future refactoring easier by using
slugs as an extension of the section. (Hugo terminology)
- What the above boils down to is this PR attempts to use directory
organization as URL management. e.g. `usage/comparison.en-us.md` ->
`en-us/usage/comparison/`, `usage/packages/overview.en-us.md` ->
`en-us/usage/packages/overview/`
- Technically we could even remove `slug`, as Hugo defaults to using
filename, however at least with this PR it means `slug` only needs to be
the name for the **current file** rather than an entire URL
2. This PR adds appropriate aliases (redirects) for pages, so anything
on the internet that links to our docs should hopefully not break.
3. A minor nit I've had for a while, renaming `seek-help` to `support`.
It's a minor thing, but `seek-help` has a strange connotation to it.
4. The commits are split such that you can review the first which is the
"actual" change, and the second is added redirects so that the first
doesn't break links elsewhere.
---------
Signed-off-by: jolheiser <john.olheiser@gmail.com>
2023-04-27 23:33:41 -04:00
aliases:
- /en-us/command-line
2017-11-26 16:44:32 -05:00
menu:
sidebar:
2023-03-23 11:18:24 -04:00
parent: "administration"
2017-11-26 16:44:32 -05:00
name: "Command Line"
2023-07-26 00:53:13 -04:00
sidebar_position: 1
2017-11-26 16:44:32 -05:00
identifier: "command-line"
---
2020-12-07 23:52:26 -05:00
# Command Line
2017-11-26 16:44:32 -05:00
2020-12-07 23:52:26 -05:00
## Usage
2017-11-26 16:44:32 -05:00
2019-04-29 14:08:21 -04:00
`gitea [global options] command [command or global options] [arguments...]`
2017-11-26 16:44:32 -05:00
2020-12-07 23:52:26 -05:00
## Global options
2019-04-29 14:08:21 -04: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` ).
2023-07-19 05:22:57 -04:00
- `--work-path path` , `-w path` : Gitea's work path. Optional. (default: the binary's path or `$GITEA_WORK_DIR` )
- `--custom-path path` , `-C path` : Gitea's custom folder path. Optional. (default: `WorkPath` /custom or `$GITEA_CUSTOM` ).
- `--config path` , `-c path` : Gitea configuration file path. Optional. (default: `CustomPath` /conf/app.ini).
2019-05-14 11:20:35 -04:00
NB: The defaults custom-path, config and work-path can also be
changed at build time (if preferred).
2017-11-26 16:44:32 -05:00
2020-12-07 23:52:26 -05:00
## Commands
2017-11-26 16:44:32 -05:00
2020-12-07 23:52:26 -05:00
### web
2018-01-08 17:48:42 -05:00
Starts the server:
2017-11-26 16:44:32 -05:00
- Options:
2020-12-09 01:47:06 -05: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.
2021-06-26 20:56:58 -04:00
- `--quiet` , `-q` : Only emit Fatal logs on the console for logs emitted before logging set up.
- `--verbose` : Emit tracing logs on the console for logs emitted before logging is set-up.
2017-11-26 16:44:32 -05:00
- Examples:
2020-12-09 01:47:06 -05:00
- `gitea web`
- `gitea web --port 80`
- `gitea web --config /etc/gitea.ini --pid /some/custom/gitea.pid`
2017-11-26 16:44:32 -05:00
- Notes:
2020-12-09 01:47:06 -05: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-26 16:44:32 -05:00
2020-12-07 23:52:26 -05:00
### admin
2018-01-08 17:48:42 -05:00
Admin operations:
2017-11-26 16:44:32 -05:00
- Commands:
2020-12-09 01:47:06 -05: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 02:57:32 -05: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 01:47:06 -05:00
- Examples:
- `gitea admin user delete --id 1`
2021-11-03 01:27:35 -04:00
- `create` :
- Options:
2021-11-28 08:28:30 -05:00
- `--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.
2021-11-03 01:27:35 -04:00
- `--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`
2020-12-09 01:47:06 -05:00
- `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`
2023-02-14 17:12:19 -05:00
- `must-change-password` :
- Args:
- `[username...]` : Users that must change their passwords
- Options:
- `--all` , `-A` : Force a password change for all users
- `--exclude username` , `-e username` : Exclude the given user. Can be set multiple times.
- `--unset` : Revoke forced password change for the given users
2023-06-26 01:13:20 -04:00
- `generate-access-token` :
- Options:
- `--username value` , `-u value` : Username. Required.
- `--token-name value` , `-t value` : Token name. Required.
- `--scopes value` : Comma-separated list of scopes. Scopes follow the format `[read|write]:<block>` or `all` where `<block>` is one of the available visual groups you can see when opening the API page showing the available routes (for example `repo` ).
- Examples:
- `gitea admin user generate-access-token --username myname --token-name mytoken`
- `gitea admin user generate-access-token --help`
2020-12-09 01:47:06 -05:00
- `regenerate`
- Options:
2021-12-23 22:56:57 -05:00
- `hooks` : Regenerate Git Hooks for all repositories
2020-12-09 01:47:06 -05:00
- `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.
2023-02-05 23:12:13 -05:00
- `--custom-tenant-id` : Use custom Tenant ID for OAuth endpoints.
2020-12-09 01:47:06 -05:00
- `--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).
2020-12-28 03:39:12 -05:00
- `--icon-url` : Custom icon URL for OAuth2 login source.
2022-02-03 12:00:34 -05:00
- `--skip-local-2fa` : Allow source to override local 2FA. (Optional)
2022-01-09 06:53:03 -05:00
- `--scopes` : Additional scopes to request for this OAuth2 source. (Optional)
2021-12-14 03:37:11 -05:00
- `--required-claim-name` : Claim name that has to be set to allow users to login with this source. (Optional)
- `--required-claim-value` : Claim value that has to be set to allow users to login with this source. (Optional)
- `--group-claim-name` : Claim name providing group names for this source. (Optional)
- `--admin-group` : Group Claim value for administrator users. (Optional)
- `--restricted-group` : Group Claim value for restricted users. (Optional)
2023-02-08 01:44:42 -05:00
- `--group-team-map` : JSON mapping between groups and org teams. (Optional)
- `--group-team-map-removal` : Activate automatic team membership removal depending on groups. (Optional)
2020-12-09 01:47:06 -05:00
- 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.
2023-02-05 23:12:13 -05:00
- `--custom-tenant-id` : Use custom Tenant ID for OAuth endpoints.
2020-12-09 01:47:06 -05:00
- `--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).
2020-12-28 03:39:12 -05:00
- `--icon-url` : Custom icon URL for OAuth2 login source.
2022-02-03 12:00:34 -05:00
- `--skip-local-2fa` : Allow source to override local 2FA. (Optional)
2022-01-09 06:53:03 -05:00
- `--scopes` : Additional scopes to request for this OAuth2 source.
2021-12-14 03:37:11 -05:00
- `--required-claim-name` : Claim name that has to be set to allow users to login with this source. (Optional)
- `--required-claim-value` : Claim value that has to be set to allow users to login with this source. (Optional)
- `--group-claim-name` : Claim name providing group names for this source. (Optional)
- `--admin-group` : Group Claim value for administrator users. (Optional)
- `--restricted-group` : Group Claim value for restricted users. (Optional)
2020-12-09 01:47:06 -05:00
- Examples:
- `gitea admin auth update-oauth --id 1 --name external-github-updated`
2022-01-12 17:54:53 -05:00
- `add-smtp` :
- Options:
- `--name` : Application Name. Required.
- `--auth-type` : SMTP Authentication Type (PLAIN/LOGIN/CRAM-MD5). Default to PLAIN.
- `--host` : SMTP host. Required.
- `--port` : SMTP port. Required.
- `--force-smtps` : SMTPS is always used on port 465. Set this to force SMTPS on other ports.
- `--skip-verify` : Skip TLS verify.
- `--helo-hostname` : Hostname sent with HELO. Leave blank to send current hostname.
- `--disable-helo` : Disable SMTP helo.
- `--allowed-domains` : Leave empty to allow all domains. Separate multiple domains with a comma (',').
- `--skip-local-2fa` : Skip 2FA to log on.
- `--active` : This Authentication Source is Activated.
Remarks:
`--force-smtps` , `--skip-verify` , `--disable-helo` , `--skip-loca-2fs` and `--active` options can be used in form:
- `--option` , `--option=true` to enable
- `--option=false` to disable
If those options are not specified value would not be changed in `update-smtp` or would use default `false` value in `add-smtp`
- Examples:
- `gitea admin auth add-smtp --name ldap --host smtp.mydomain.org --port 587 --skip-verify --active`
- `update-smtp` :
- Options:
- `--id` : ID of source to be updated. Required.
- other options are shared with `add-smtp`
- Examples:
- `gitea admin auth update-smtp --id 1 --host smtp.mydomain.org --port 587 --skip-verify=false`
- `gitea admin auth update-smtp --id 1 --active=false`
2020-12-09 01:47:06 -05:00
- `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’ ’
2021-09-26 22:39:36 -04:00
- `--avatar-attribute value` : The attribute of the user’ ’
2020-12-09 01:47:06 -05:00
- `--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:
2023-05-05 14:18:53 -04:00
- `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=%[1]s)(mail=%[1]s)))" --email-attribute mail`
2020-12-09 01:47:06 -05:00
- `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’ ’
2021-09-26 22:39:36 -04:00
- `--avatar-attribute value` : The attribute of the user’ ’
2020-12-09 01:47:06 -05:00
- `--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’ ’
2021-09-26 22:39:36 -04:00
- `--avatar-attribute value` : The attribute of the user’ ’
2020-12-09 01:47:06 -05:00
- `--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’ ’
2021-09-26 22:39:36 -04:00
- `--avatar-attribute value` : The attribute of the user’ ’
2020-12-09 01:47:06 -05:00
- `--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-26 16:44:32 -05:00
2020-12-07 23:52:26 -05:00
### cert
2018-01-08 17:48:42 -05: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-26 16:44:32 -05:00
- Options:
2021-02-19 11:29:22 -05:00
- `--host value` : Comma separated hostnames and ips which this certificate is valid for.
2020-12-09 01:47:06 -05:00
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
2023-08-27 20:53:16 -04:00
set. (default: 3072).
2020-12-09 01:47:06 -05:00
- `--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-26 16:44:32 -05:00
- Examples:
2020-12-09 01:47:06 -05:00
- `gitea cert --host git.example.com,example.com,www.example.com --ca`
2017-11-26 16:44:32 -05:00
2020-12-07 23:52:26 -05:00
### dump
2018-01-08 17:48:42 -05: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-26 16:44:32 -05:00
- Options:
2020-12-09 01:47:06 -05: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.
2021-02-07 20:00:12 -05:00
- `--skip-custom-dir` : Skip dumping of the custom dir. Optional.
2022-04-26 16:30:51 -04:00
- `--skip-lfs-data` : Skip dumping of LFS data. Optional.
- `--skip-attachment-data` : Skip dumping of attachment data. Optional.
- `--skip-package-data` : Skip dumping of package data. Optional.
- `--skip-log` : Skip dumping of log data. Optional.
2023-09-03 14:44:01 -04:00
- `--database` , `-d` : Specify the database SQL syntax. Optional (supported arguments: sqlite3, mysql, mssql, postgres).
2020-12-09 01:47:06 -05:00
- `--verbose` , `-V` : If provided, shows additional details. Optional.
2023-09-03 14:44:01 -04:00
- `--type` : Set the dump output format. Optional. (formats: zip, tar, tar.sz, tar.gz, tar.xz, tar.bz2, tar.br, tar.lz4, tar.zst default: zip).
2017-11-26 16:44:32 -05:00
- Examples:
2020-12-09 01:47:06 -05:00
- `gitea dump`
- `gitea dump --verbose`
2018-02-18 22:23:41 -05:00
2020-12-07 23:52:26 -05:00
### generate
2018-02-18 22:23:41 -05:00
Generates random values and tokens for usage in configuration file. Useful for generating values
for automatic deployments.
- Commands:
2020-12-09 01:47:06 -05: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 09:41:07 -04:00
2020-12-07 23:52:26 -05:00
### keys
2018-11-01 09:41:07 -04: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
2021-11-28 08:28:30 -05:00
# username running Gitea
2018-11-01 09:41:07 -04:00
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` .
2021-11-28 08:28:30 -05:00
NB: opensshd requires the Gitea program to be owned by root and not
2018-11-01 09:41:07 -04:00
writable by group or others. The program must be specified by an absolute
path.
2019-12-16 20:49:07 -05:00
NB: Gitea must be running for this command to succeed.
2019-11-05 13:54:54 -05:00
2020-12-07 23:52:26 -05:00
### migrate
2020-12-09 01:47:06 -05:00
2022-07-27 21:22:47 -04:00
Migrates the database. This command can be used to run other commands before starting the server for the first time.
2019-11-05 13:54:54 -05:00
This command is idempotent.
2023-07-25 10:38:27 -04:00
### doctor check
2020-12-09 01:47:06 -05:00
2023-07-25 10:38:27 -04:00
Diagnose and potentially fix problems with the current Gitea instance.
Several checks are run by default, but additional ones can be run:
2020-01-11 09:24:57 -05:00
2023-07-25 10:38:27 -04:00
- `gitea doctor check --list` - will list all the available checks
- `gitea doctor check --all` - will run all available checks
- `gitea doctor check --default` - will run the default checks
- `gitea doctor check --run [check(s),]...` - will run the named checks
2020-12-09 01:47:06 -05:00
2023-07-25 10:38:27 -04:00
Some problems can be automatically fixed by passing the `--fix` option.
Extra logging can be set with `--log-file=...` .
2020-07-05 20:07:07 -04:00
2020-12-07 23:52:26 -05:00
#### doctor recreate-table
2020-09-06 17:52:01 -04: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:
```
2023-08-13 15:17:21 -04:00
2020/08/02 11:32:29 ...rm/session_schema.go:360:Sync() [W] Table user Column keep_activity_private db default is , struct default is 0
2020-09-06 17:52:01 -04:00
```
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
```
2021-11-28 08:28:30 -05:00
You can ask Gitea to recreate multiple tables using:
2020-09-06 17:52:01 -04:00
```
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.
2023-07-25 10:38:27 -04:00
### doctor convert
Converts a MySQL database from utf8 to utf8mb4 or a MSSQL database from varchar to nvarchar.
2020-12-07 23:52:26 -05:00
### manager
2020-07-05 20:07:07 -04:00
Manage running server operations:
- Commands:
2020-12-09 01:47:06 -05: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-05 20:07:07 -04: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 01:47:06 -05:00
- `logging` : Adjust logging commands
2020-07-05 20:07:07 -04:00
- Commands:
2020-12-09 01:47:06 -05:00
- `pause` : Pause logging
2020-07-05 20:07:07 -04: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 01:47:06 -05:00
- `resume` : Resume logging
2020-07-05 20:07:07 -04: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 01:47:06 -05:00
- `add` : Add a logger
2020-07-05 20:07:07 -04: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 01:47:06 -05:00
- `--name value` , `-n value` : Name of the new logger - will default to mode
2020-07-05 20:07:07 -04: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 01:12:22 -05:00
- `--filename value` , `-f value` : Filename for the logger -
2020-07-05 20:07:07 -04: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 01:47:06 -05:00
- `--name value` , `-n value` : Name of the new logger - will default to mode
2020-07-05 20:07:07 -04: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
2022-03-31 13:01:43 -04:00
- `processes` : Display Gitea processes and goroutine information
- Options:
- `--flat` : Show processes as flat table rather than as tree
- `--no-system` : Do not show system processes
- `--stacktraces` : Show stacktraces for goroutines associated with processes
- `--json` : Output as json
- `--cancel PID` : Send cancel to process with PID. (Only for non-system processes.)
2020-12-26 22:34:19 -05:00
### dump-repo
2021-12-23 22:56:57 -05:00
Dump-repo dumps repository data from Git/GitHub/Gitea/GitLab:
2020-12-26 22:34:19 -05:00
- Options:
- `--git_service service` : Git service, it could be `git` , `github` , `gitea` , `gitlab` , If clone_addr could be recognized, this could be ignored.
2022-07-27 21:22:47 -04:00
- `--repo_dir dir` , `-r dir` : Repository dir path to store the data
2020-12-26 22:34:19 -05:00
- `--clone_addr addr` : The URL will be clone, currently could be a git/github/gitea/gitlab http/https URL. i.e. https://github.com/lunny/tango.git
- `--auth_username lunny` : The username to visit the clone_addr
- `--auth_password <password>` : The password to visit the clone_addr
- `--auth_token <token>` : The personal token to visit the clone_addr
- `--owner_name lunny` : The data will be stored on a directory with owner name if not empty
- `--repo_name tango` : The data will be stored on a directory with repository name if not empty
- `--units <units>` : Which items will be migrated, one or more units should be separated as comma. wiki, issues, labels, releases, release_assets, milestones, pull_requests, comments are allowed. Empty means all units.
### restore-repo
Restore-repo restore repository data from disk dir:
- Options:
- `--repo_dir dir` , `-r dir` : Repository dir path to restore from
- `--owner_name lunny` : Restore destination owner name
- `--repo_name tango` : Restore destination repository name
2020-12-28 03:39:12 -05:00
- `--units <units>` : Which items will be restored, one or more units should be separated as comma. wiki, issues, labels, releases, release_assets, milestones, pull_requests, comments are allowed. Empty means all units.
2023-04-17 13:07:13 -04:00
### actions generate-runner-token
Generate a new token for a runner to use to register with the server
- Options:
- `--scope {owner}[/{repo}]` , `-s {owner}[/{repo}]` : To limit the scope of the runner, no scope means the runner can be used for all repos, but you can also limit it to a specific repo or owner
To register a global runner:
```
gitea actions generate-runner-token
```
To register a runner for a specific organization, in this case `org` :
```
gitea actions generate-runner-token -s org
```
To register a runner for a specific repo, in this case `username/test-repo` :
```
gitea actions generate-runner-token -s username/test-repo
```
