# Backup, Restore, and Disaster Recovery service (freezer) command-line client

The freezer client is the command-line interface (CLI) for the Backup, Restore, and Disaster Recovery service (freezer) API and its extensions.

This chapter documents freezer version `1.7.1`.

For help on a specific freezer command, enter:

    $ freezer help COMMAND

## freezer usage

    usage: freezer [--version] [-v | -q] [--log-file LOG_FILE] [-h] [--debug]
                   [--os-auth-url OS_AUTH_URL] [--os-backup-url OS_BACKUP_URL]
                   [--os-backup-api-version OS_BACKUP_API_VERSION]
                   [--os-endpoint-type OS_ENDPOINT_TYPE]
                   [--os-password OS_PASSWORD] [--os-username OS_USERNAME]
                   [--os-token OS_TOKEN]
                   [--os-project-domain-name OS_PROJECT_DOMAIN_NAME]
                   [--os-project-domain-id OS_PROJECT_DOMAIN_ID]
                   [--os-project-name OS_PROJECT_NAME]
                   [--os-region-name OS_REGION_NAME]
                   [--os-project-id OS_PROJECT_ID]
                   [--os-user-domain-name OS_USER_DOMAIN_NAME]
                   [--os-user-domain-id OS_USER_DOMAIN_ID] [-k]
                   [--os-cacert OS_CACERT] [--os-cert OS_CERT]

## freezer optional arguments

`--version`

  show program’s version number and exit

`-v, --verbose`

  Increase verbosity of output. Can be repeated.

`-q, --quiet`

  Suppress output except warnings and errors.

`--log-file LOG_FILE`

  Specify a file to log output. Disabled by default.

`-h, --help`

  Show help message and exit.

`--debug`

  Show tracebacks on errors.

`--os-auth-url OS_AUTH_URL`

  Specify identity endpoint

`--os-backup-url OS_BACKUP_URL`

  Specify the Freezer backup service endpoint to use

`--os-backup-api-version OS_BACKUP_API_VERSION`

  Backup API version: 1 or 2

`--os-endpoint-type OS_ENDPOINT_TYPE`

  Endpoint type to select. Valid endpoint types: “public” or “publicURL”, “internal” or “internalURL”, “admin” or “adminURL”

`--os-password OS_PASSWORD`

  Password used for authentication with the OpenStack Identity service

`--os-username OS_USERNAME`

  Name used for authentication with the OpenStack Identity service

`--os-token OS_TOKEN`

  Specify an existing token to use instead of retrieving one via authentication

`--os-project-domain-name OS_PROJECT_DOMAIN_NAME`

  Domain name containing project

`--os-project-domain-id OS_PROJECT_DOMAIN_ID`

  OpenStack project domain ID. Defaults to `env[OS_PROJECT_ID]`.

`--os-project-name OS_PROJECT_NAME`

  Project name to scope to

`--os-region-name OS_REGION_NAME`

  Specify the region to use

`--os-project-id OS_PROJECT_ID`

  Project to request authorization on

`--os-user-domain-name OS_USER_DOMAIN_NAME`

  User domain name

`--os-user-domain-id OS_USER_DOMAIN_ID`

  OpenStack user domain ID. Defaults to `env[OS_USER_DOMAIN_ID]`.

`-k, --insecure`

  use python-freezerclient with insecure connections

`--os-cacert OS_CACERT`

  Path of CA TLS certificate(s) used to verify the remote server’s certificate. Without this option freezer looks for the default system CA certificates.

`--os-cert OS_CERT`

  Path of CERT TLS certificate(s) used to verify the remote server’s certificate.1

### freezer action-create

    usage: freezer action-create [-h] --file FILE

Create an action from a file

Optional arguments:

`-h, --help`

  show this help message and exit

`--file FILE`

  Path to json file with the action

### freezer action-delete

    usage: freezer action-delete [-h] action_id

Delete an action from the api

Positional arguments:

`action_id`

  ID of the action

Optional arguments:

`-h, --help`

  show this help message and exit

### freezer action-list

    usage: freezer action-list [-h] [-f {csv,html,json,table,value,yaml}]
                               [-c COLUMN] [--max-width <integer>] [--fit-width]
                               [--print-empty] [--noindent]
                               [--quote {all,minimal,none,nonnumeric}]
                               [--limit LIMIT] [--offset OFFSET] [--search SEARCH]

List all actions for your user

Optional arguments:

`-h, --help`

  show this help message and exit

`--limit LIMIT`

  Specify a limit for search query

`--offset OFFSET`

`--search SEARCH`

  Define a filter for the query.

  If the storage of freezer-api is a `Sqlalchemy` database, the search option must be a list of {key, value}, and it can be converted to json, otherwise, search option will not work, querying all records. as follows:

  > - ‘[{“max_retries”: 10}]’

  > - ‘[{“max_retries”: 10}, {“mode”: “nova”}]’

  `Note`:

    If all key-values of the list are found in this tuple, it will be filtered in, otherwise filtered out.

  If the storage of freezer-api is an `elasticsearch` database, the search option can be the same as above, or it can be a string that it isn’t {key, value}. plsease reference elasticsearch https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html as follows:

  > - ‘[{“max_retries”: 10}]’

  > - ‘[{“max_retries”: 10}, {“mode”: “nova”}]’

  > - ‘[“5e37946b10dc42dbb6ca3338501da2c7”]’

### freezer action-show

    usage: freezer action-show [-h] [-f {html,json,shell,table,value,yaml}]
                               [-c COLUMN] [--max-width <integer>] [--fit-width]
                               [--print-empty] [--noindent] [--prefix PREFIX]
                               action_id

Show a single action

Positional arguments:

`action_id`

  ID of the action

Optional arguments:

`-h, --help`

  show this help message and exit

### freezer action-update

    usage: freezer action-update [-h] action_id file

Update an action from a file

Positional arguments:

`action_id`

  ID of the session

`file`

  Path to json file with the action

Optional arguments:

`-h, --help`

  show this help message and exit

### freezer backup-delete

    usage: freezer backup-delete [-h] backup_uuid

Delete a backup from the api

Positional arguments:

`backup_uuid`

  UUID of the backup

Optional arguments:

`-h, --help`

  show this help message and exit

### freezer backup-list

    usage: freezer backup-list [-h] [-f {csv,html,json,table,value,yaml}]
                               [-c COLUMN] [--max-width <integer>] [--fit-width]
                               [--print-empty] [--noindent]
                               [--quote {all,minimal,none,nonnumeric}]
                               [--limit LIMIT] [--offset OFFSET] [--search SEARCH]

List all backups for your user

Optional arguments:

`-h, --help`

  show this help message and exit

`--limit LIMIT`

  Specify a limit for search query

`--offset OFFSET`

`--search SEARCH`

  Define a filter for the query. See `freezer action-list`

### freezer backup-show

    usage: freezer backup-show [-h] [-f {html,json,shell,table,value,yaml}]
                               [-c COLUMN] [--max-width <integer>] [--fit-width]
                               [--print-empty] [--noindent] [--prefix PREFIX]
                               backup_uuid

Show the metadata of a single backup

Positional arguments:

`backup_uuid`

  ID of the backup

Optional arguments:

`-h, --help`

  show this help message and exit

### freezer client-delete

    usage: freezer client-delete [-h] client_id

Delete a client from the api

Positional arguments:

`client_id`

  ID of the client

Optional arguments:

`-h, --help`

  show this help message and exit

### freezer client-list

    usage: freezer client-list [-h] [-f {csv,html,json,table,value,yaml}]
                               [-c COLUMN] [--max-width <integer>] [--fit-width]
                               [--print-empty] [--noindent]
                               [--quote {all,minimal,none,nonnumeric}]
                               [--limit LIMIT] [--offset OFFSET] [--search SEARCH]

List of clients registered in the api

Optional arguments:

`-h, --help`

  show this help message and exit

`--limit LIMIT`

  Specify a limit for search query

`--offset OFFSET`

`--search SEARCH`

  Define a filter for the query. See `freezer action-list`

### freezer client-register

    usage: freezer client-register [-h] --file FILE

Register a new client

Optional arguments:

`-h, --help`

  show this help message and exit

`--file FILE`

  Path to json file with the client

### freezer client-show

    usage: freezer client-show [-h] [-f {html,json,shell,table,value,yaml}]
                               [-c COLUMN] [--max-width <integer>] [--fit-width]
                               [--print-empty] [--noindent] [--prefix PREFIX]
                               client_id

Show a single client

Positional arguments:

`client_id`

  ID of the client

Optional arguments:

`-h, --help`

  show this help message and exit

### freezer job-abort

    usage: freezer job-abort [-h] job_id

Abort a running job

Positional arguments:

`job_id`

  ID of the job

Optional arguments:

`-h, --help`

  show this help message and exit

### freezer job-create

    usage: freezer job-create [-h] --file FILE --client CLIENT_ID

Create a new job from a file

Optional arguments:

`-h, --help`

  show this help message and exit

`--file FILE`

  Path to json file with the job

`--client CLIENT_ID, -C`

  CLIENT_ID Select a client for this job

### freezer job-delete

    usage: freezer job-delete [-h] job_id

Delete a job from the api

Positional arguments:

`job_id`

  ID of the job

Optional arguments:

`-h, --help`

  show this help message and exit

### freezer job-get

    usage: freezer job-get [-h] [--no-format] job_id

Download a job as a json file

Positional arguments:

`job_id`

  ID of the job

Optional arguments:

`-h, --help`

  show this help message and exit

`--no-format`

  Return a job in json without pretty print

### freezer job-list

    usage: freezer job-list [-h] [-f {csv,html,json,table,value,yaml}] [-c COLUMN]
                            [--max-width <integer>] [--fit-width] [--print-empty]
                            [--noindent] [--quote {all,minimal,none,nonnumeric}]
                            [--limit LIMIT] [--offset OFFSET] [--search SEARCH]
                            [--client CLIENT_ID]

List all the jobs for your user

Optional arguments:

`-h, --help`

  show this help message and exit

`--limit LIMIT`

  Specify a limit for search query

`--offset OFFSET`

`--search SEARCH`

  Define a filter for the query. See `freezer action-list`

`--client CLIENT_ID, -C`

  CLIENT_ID Get jobs for a specific client

### freezer job-show

    usage: freezer job-show [-h] [-f {html,json,shell,table,value,yaml}]
                            [-c COLUMN] [--max-width <integer>] [--fit-width]
                            [--print-empty] [--noindent] [--prefix PREFIX]
                            job_id

Show a single job

Positional arguments:

`job_id`

  ID of the job

Optional arguments:

`-h, --help`

  show this help message and exit

### freezer job-start

    usage: freezer job-start [-h] job_id

Send a start signal for a job

Positional arguments:

`job_id`

  ID of the job

Optional arguments:

`-h, --help`

  show this help message and exit

### freezer job-stop

    usage: freezer job-stop [-h] job_id

Send a stop signal for a job

Positional arguments:

`job_id`

  ID of the job

Optional arguments:

`-h, --help`

  show this help message and exit

### freezer job-update

    usage: freezer job-update [-h] job_id file

Update a job from a file

Positional arguments:

`job_id`

  ID of the job

`file`

  Path to json file with the job

Optional arguments:

`-h, --help`

  show this help message and exit

### freezer session-add-job

    usage: freezer session-add-job [-h] --session-id SESSION_ID --job-id JOB_ID

Add a job to a session

Optional arguments:

`-h, --help`

  show this help message and exit

`--session-id SESSION_ID`

  ID of the session

`--job-id JOB_ID`

  ID of the job to add

### freezer session-create

    usage: freezer session-create [-h] --file FILE

Create a session from a file

Optional arguments:

`-h, --help`

  show this help message and exit

`--file FILE`

  Path to json file with the job

### freezer session-delete

    usage: freezer session-delete [-h] session_id

Delete a session

Positional arguments:

`session_id`

  ID of the session

Optional arguments:

`-h, --help`

  show this help message and exit

### freezer session-list

    usage: freezer session-list [-h] [-f {csv,html,json,table,value,yaml}]
                                [-c COLUMN] [--max-width <integer>] [--fit-width]
                                [--print-empty] [--noindent]
                                [--quote {all,minimal,none,nonnumeric}]
                                [--limit LIMIT] [--offset OFFSET]
                                [--search SEARCH]

List all the sessions for your user

Optional arguments:

`-h, --help`

  show this help message and exit

`--limit LIMIT`

  Specify a limit for search query

`--offset OFFSET`

`--search SEARCH`

  Define a filter for the query. See `freezer action-list`

### freezer session-remove-job

    usage: freezer session-remove-job [-h] --session-id SESSION_ID --job-id JOB_ID

Remove a job from a session

Optional arguments:

`-h, --help`

  show this help message and exit

`--session-id SESSION_ID`

  ID of the session

`--job-id JOB_ID`

  ID of the job to add

### freezer session-show

    usage: freezer session-show [-h] [-f {html,json,shell,table,value,yaml}]
                                [-c COLUMN] [--max-width <integer>] [--fit-width]
                                [--print-empty] [--noindent] [--prefix PREFIX]
                                session_id

Show a single session

Positional arguments:

`session_id`

  ID of the session

Optional arguments:

`-h, --help`

  show this help message and exit

### freezer session-start

    usage: freezer session-start [-h] --session-id SESSION_ID --job-id JOB_ID
                                 --job-tag JOB_TAG

Start a session

Optional arguments:

`-h, --help`

  show this help message and exit

`--session-id SESSION_ID`

  ID of the session

`--job-id JOB_ID`

  ID of the job

`--job-tag JOB_TAG`

  Job tag value

### freezer session-update

    usage: freezer session-update [-h] session_id file

Update a session from a file

Positional arguments:

`session_id`

  ID of the session

`file`

  Path to json file with the session

Optional arguments:

`-h, --help`

  show this help message and exit

this page last updated: 2026-02-27 17:06:00

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug