Command Line Archive & Restore

The flame_archive tool, located in /opt/Autodesk/io/bin, allows you to archive and restore material directly from the command line. Adding the directory to your PATH environment variable makes the program more easily accessible.

Modes of Operation

flame_archive supports the following modes of operation:

Formatting (-f): Creates an empty archive in a specified location.
Listing (-l): Browses projects or archives to determine the identifiers of elements to archive or restore.
Estimating (-e): Determines the size of material to archive or restore.
Archiving (-a): Appends selected project entries to an existing archive. The appended entries are grouped under an archive session.
Restoring (-r): Restores selected archive entries to a specified project location.
Converting (-c): Converts an older, read-only archive to the current format, allowing it to be appended to.

Use flame_archive --help to retrieve a general overview of available options. For detailed usage instructions specific to a mode, use flame_archive <mode> --help.

For example, this command provides help for the listing mode:

$ flame_archive -l --help

Creating an Archive

Before adding contents to an archive, you must first create one through a process called formatting. Formatting sets the ownership, permissions, and storage management constructs required for archiving. It also defines the segment size, which splits the archive into multiple files (segments or volumes). This is useful when a single storage device cannot accommodate the entire archive or when storing the archive on fixed size offline media like tape.

The default segment size is 1 GB but can be changed using the -i option.

Important: By default, flame_archive uses the active shell's umask and the primary group of the user running it. Adjust these settings for secure, restricted workflows.

Creating a standard archive

The following commands create an archive in the /home/ted/archives/projectX directory with the file name prefix ProjectX_Daily and a segment size of 50 GB:
```
$ mkdir -p /home/ted/archives/projectX
$ flame_archive -f -F /home/ted/archives/projectX/ProjectX_Daily -i 50
```
Note: The -F option specifies the archive to work with. Its argument must be an absolute path to the archive header file.
Creating a group-restricted archive

The following commands create a group-restricted archive named target_profiles for projects belonging to the MI6 group:
```
$ umask 007
$ flame_archive -f -F /home/MI6/archive/target_profiles -G MI6
```
Note: Refer to File Security for more information about secure workflows.

Retrieving Identifiers

To archive or restore specific entries from a project or archive, you need to retrieve their unique identifiers. These identifiers allow precise selection of the desired entries.

Listing entries from a project

Use the listing mode to retrieve the identifiers of project entries:

$ flame_archive -l -P ProjectX -u

    Project                        : ProjectX                 4405130a_67e3dfe6_000048f0
      Workspace                    :   Workspace                4405130a_67e3dfe8_00041521
        Desktop                    :     Desktop                  4405130a_67e3dfe8_00041524
          Batch Container          :       Batch                    4405130a_67e3dfe8_00041526
            Saved Batch            :         <batch name>_<iteration###>4405130a_67e3dfe8_00041528
              Reel                 :           Schematic Reel 1         4405130a_67e3dfe8_0004152a
              Reel                 :           Schematic Reel 2         4405130a_67e3dfe8_0004152c
              Reel                 :           Schematic Reel 3         4405130a_67e3dfe8_0004152e
              BatchSetupReel       :           Setup                    4405130a_67e3dfe8_00041530
            Reels                  :         Batch Shelf              4405130a_67e3dfe8_00041532
              Reel                 :           Batch Renders            4405130a_67e3dfe8_00041534
            Saved Batch List       :         Iterations               4405130a_67e3dfe8_00041536
          Reel Group               :       Reels                    4405130a_67e3dfe8_00041538
            Reel                   :         Reel 1                   4405130a_67e3dfe8_0004153c
            Reel                   :         Reel 2                   4405130a_67e3dfe8_0004153e
            Reel                   :         Reel 3                   4405130a_67e3dfe8_00041540
              Clip                 :           DPX_10bit_UHDTV          4405130a_67e3e101_000bc527
                Process            :             DPX_10bit_UHDTV          
                Process            :             DPX_10bit_UHDTV          
            Reel                   :         Reel 4                   4405130a_67e3dfe8_00041542
            Reel                   :         Sequences                4405130a_67e3dfe8_00041544
        Entry                      :     Open Sequences           4405130a_67e3dfe8_00041523
        Library List               :     Libraries                4405130a_67e3dfe8_00041546
          Library                  :       Default Library          4405130a_67e3dfe8_00041548
            Clip                   :         DPX_10bit_UHDTV          4405130a_67e3dfe8_0004154a
              Process              :           DPX_10bit_UHDTV          
              Process              :           DPX_10bit_UHDTV          
          Library                  :       Grabbed References       4405130a_67e3dfe8_0004155a
          Library                  :       Timeline FX              4405130a_67e3dfe8_0004155c
      Library List                 :   Shared Libraries         4405130a_67e3dfe6_000048f3
    ...

The rightmost column shows the project entry identifiers as triplets of 32-bit hexadecimal numbers separated by underscores (_). Entries without identifiers, such as the Process entries above, cannot be individually selected.

Note: The -P switch specifies the project to work with. Its argument can be either a project name or a UUID. Use a UUID to disambiguate if two or more projects have the same name. You can retrieve the project UUID using one of the methods described here.

Listing entries from an archive

The listing mode is also used to retrieve identifiers from an archive:

$ flame_archive -l -F /home/ted/archives/projectX/ProjectX_Daily -u

...
[ Table of Contents ]

Type and Name                                 Dur    A  Creation        Location     PbUid                            

--------------------------------------------  -----  -  --------------  -----------  -------------------------------------

* Archive Session - 2025/04/09 12:52:49                 25/04/09 12:52               H_1824294922_S_1744217569_U_373808
  C Hist001                                      10  A  25/04/09 12:52  <multiple>   H_1824294922_S_1744217569_U_373749
    E render71                                   10     15/07/13 13:17             
    E excerpt 3                                  24     15/06/16 14:53             
    E excerpt 3                                  24  A  15/06/16 14:53             
    E excerpt 3                                  24  A  15/06/16 14:53             
...

The rightmost column (PbUid) again shows the entry identifiers using a host/second/microsecond (HSU) decimal format. The hexadecimal triplet IDs and the HSU IDs are interchangeable.

Selecting Entries

The flame_archive tool provides several options for selecting specific entries when archiving or restoring. These options allow you to target specific workspaces, libraries, or individual entries, ensuring precise control over the operation.

Selecting Within a Project

When archiving or restoring, you may want to restrict the operation to specific entries rather than the entire project. The -W, -L, -E, and -B options allow you to select specific entries. The first three can be used for both origin (archiving) and target (restoring) selection, while -B is limited to origin selection.

Selector	Action
`-W <workspace name>`	Selects the workspace entry for archiving or as the destination of a restore operation.
`-L <library name>`	Selects the library entry for archiving or as the destination of a restore operation.
`-E @<entry id>` `-E <entry path>` `-E <wiretap node id>`¹	Selects the entry for archiving or as the destination of a restore operation.
`-B <@<entry id>\n list file>`	Selects multiple entries for archiving.

¹ Use wiretap_print_tree to retrieve node IDs. Wiretap node IDs in flame_archive must not include a trailing /. Using Wiretap node IDs also precludes the use of -P, -W, or -L.

Note: Entry paths may not always uniquely identify an entry. Multiple entries with the same name can exist within the same parent entry. Consider this limitation when choosing a selection option.

Examples

Select a library within a workspace

$ flame_archive -l -P ProjectX -W Workspace -L "Default Library" -u

Library                        : Default Library          4405130a_67e3dfe8_00041548
  Clip                         :   DPX_10bit_UHDTV          4405130a_67e3dfe8_0004154a
    Process                    :     DPX_10bit_UHDTV          
    Process                    :     DPX_10bit_UHDTV

Select an entry by its ID

$ flame_archive -l -P ProjectX -E @4405130a_67e3dfe8_0004154a -u

  Clip                         :   DPX_10bit_UHDTV          4405130a_67e3dfe8_0004154a
    Process                    :     DPX_10bit_UHDTV          
    Process                    :     DPX_10bit_UHDTV

Select an entry by its path

$ flame_archive -l -P ProjectX -E "/Workspace/Libraries/Default Library/DPX_10bit_UHDTV" -u

  Clip                         :   DPX_10bit_UHDTV          4405130a_67e3dfe8_0004154a
    Process                    :     DPX_10bit_UHDTV          
    Process                    :     DPX_10bit_UHDTV

Select an entry using a Wiretap node ID

$ flame_archive -l -E /projects/6d3222d1-502d-4c1a-805b-e1e261078416/4405130a_67e3dfe8_00041521/4405130a_67e3dfe8_00041546/4405130a_67e3dfe8_00041548/4405130a_67e3dfe8_0004154a -u

  Clip                         :   DPX_10bit_UHDTV          4405130a_67e3dfe8_0004154a
    Process                    :     DPX_10bit_UHDTV          
    Process                    :     DPX_10bit_UHDTV

A usage example with the -B selector will be presented later in the Archiving Entries section.

Selecting Within an Archive

Archives have their own set of selectors (-S and -B) for origin selection. Unlike projects, archives do not allow target selection. Archiving operations always append a session entry at the root of the archive's table of contents.

Selector	Action
`-S @<entry id>` `-S <entry path>`	Selects the entry for restoring.
`-B <@<entry id>\n list file>`	Selects multiple entries for restoring.

Note: Entry paths may not always uniquely identify an entry. Multiple entries with the same name can exist within the same parent entry. Consider this limitation when choosing a selection option.

Examples

Select an entry by its ID

$ flame_archive -l -F /home/ted/archives/projectX/ProjectX_Daily -S @H_1824294922_S_1744217569_U_373749 -u

Clip                           : Hist001                  6cbc880a_67f6a5e1_0005b3f5
  Process                      :   render71                 
  Process                      :   excerpt 3
  Process                      :   excerpt 3
  Process                      :   excerpt 3

Select an entry by its path

$ flame_archive -l -F /home/ted/archives/projectX/ProjectX_Daily -S "/Archive Session - 2025/04/09 12:52:49/Hist001" -u

Clip                           : Hist001                  6cbc880a_67f6a5e1_0005b3f5
  Process                      :   render71                 
  Process                      :   excerpt 3
  Process                      :   excerpt 3
  Process                      :   excerpt 3

A usage example with the -B selector will be presented later in the Restoring Entries section.

Size Estimation

Estimating the required storage space for archiving or restoring tasks helps you plan ahead and avoid time-consuming interruptions or failures. The flame_archive size estimation mode provides this critical information.

Estimating the size of an archive

Use flame -e -P <project name> to determine the size of the material you want to archive:
```
$ flame_archive -e -P ProjectX -E @4405130a_67e3dfe8_00041548

63.28 MB
```

Estimating the size of a restore

Use flame -e -F <archive path> to determine the size of the material you want to restore:

$ flame_archive -e -F /home/ted/archives/projectX/ProjectX_Daily -S @H_1824294922_S_1744217569_U_373749

Size: 308.78 MB

Archiving Entries

The flame_archive tool supports most archiving options found in Flame Family creative applications. The following examples demonstrate how to use flame_archive in typical archiving workflows.

Note: Starting with flame_archive 2026, pre-2026 projects cannot be archived directly. These projects must first be converted to version 2026+ due to differences in the colour management system (SynColor vs OCIO).

Appending an entire project to an archive

This command appends the current state of project ProjectX to the archive ProjectX_Daily under a new archive session entry. All media from clips not already present in the archive will be added:
```
$ flame_archive -a -F /home/ted/archives/projectX/ProjectX_Daily -P ProjectX
```

Appending to a group-restricted archive

This example appends project `OddJob` to the `target_profiles` archive,

restricted to members of group MI6:

$ umask 007
$ flame_archive -a -F /home/MI6/archive/target_profiles -G MI6 -P OddJob

Alternatively, the command can be executed as follows:

$ echo "flame_archive -a -F /home/MI6/archive/target_profiles -P OddJob" | newgrp MI6

Note: Refer to File Security for more information about secure workflows.

Appending a metadata-only copy of a clip

This command appends a clip from ProjectX, identified by its ID, without including source caches, renders, machine learning caches, or unused versions. The clip is added to an archive session named "no-media":
```
$ flame_archive -a "no-media" -F /home/ted/archives/projectX/ProjectX_Daily -P ProjectX -E@4405130a_67e3dfe8_0004154a -k -O sources,renders,maps,unused
```
Note: If the clip contains media that cannot be relinked or re-rendered, that media is added to the archive.

Verify clips before archiving

This command appends the same clip as above, including its media, after performing a pre-verification to ensure the clip is healthy. For example, a healthy clip must not have any pending renders:

$ flame_archive -a "with-media" -F /home/ted/archives/projectX/ProjectX_Daily -P ProjectX -E@4405130a_67e3dfe8_0004154a -p

All clips from entry DPX_10bit_UHDTV are OK, and can be archived.

$ flame_archive -l -F /home/ted/archives/projectX/ProjectX_Daily

...
[ Table of Contents ]

Type and Name                                 Dur    A  Creation        Location     
--------------------------------------------  -----  -  --------------  -----------  

* no-media                                              25/04/10 15:21             
  C DPX_10bit_UHDTV                               2     25/04/10 15:21             
    E DPX_10bit_UHDTV                             2     25/03/03 15:50             
* with-media                                            25/04/10 15:34             
  C DPX_10bit_UHDTV                               2     25/04/10 15:34             
    E DPX_10bit_UHDTV                             2     25/03/03 15:50

Appending a list of entries from a file

In this example, three entry IDs from ProjectB (a library, a folder, and a clip) are added to the id_list.txt file. This file is then fed to flame_archive using the -B option.

$ sh

sh$ tee /tmp/id_list.txt << EOF
> @639a8a0a_67c79315_0005cdfa
> @639a8a0a_67c79315_0005ce06
> @639a8a0a_67c79315_0005ce12
> EOF

sh$ exit

$ flame_archive -a "file-list-no-media" -F /home/ted/archives/projectX/ProjectX_Daily -P ProjectB -B /tmp/id_list.txt -k -O sources,renders,maps,unused

After appending, the archive content can be listed:

$ flame_archive -l -F /home/ted/archives/projectX/ProjectX_Daily -u

...
[ Table of Contents ]

Type and Name                                 Dur    A  Creation        Location     PbUid
--------------------------------------------  -----  -  --------------  -----------  -------------------------------------

...
* file-list-no-media                                    25/04/10 16:00               H_1772839946_S_1744315218_U_243330
  L Soft-Import                                         25/04/10 16:00               H_1772839946_S_1744315218_U_242291
    F CompressedMedia_with_Audio                        25/04/10 16:00               H_1772839946_S_1744315218_U_242292
      C RED                                      10  A  25/04/10 16:00  <multiple>   H_1772839946_S_1744315218_U_242293
...
  F FileSequences                                       25/04/10 16:00               H_1772839946_S_1744315218_U_243093
    C Cached 2                                   10     25/04/10 16:00               H_1772839946_S_1744315218_U_243094
      E Cached 2                                 10     15/07/13 13:01
...
  C Glow and Matchbox                            10     25/04/10 16:00  <multiple>   H_1772839946_S_1744315218_U_243271
    E render71                                   10     15/07/13 13:02
    E <untitled>                                145     15/04/24 15:49

Restoring Entries

The flame_archive tool allows you to restore entire projects or specific entries from an archive to the local project database. It also enables you to specify which project entry will receive the restored entries when applicable. The following examples demonstrate common use cases for the restore mode.

Restoring a whole project

This command restores project ProjectY from the archive session named full_project in the ProjectY_Daily archive:
```
$ flame_archive -r -F /home/ted/archives/projectY/ProjectY_Daily -S /full_project/ProjectY
```
Note: If ProjectY already exists in the local database, a new project with the same name and a numeral suffix (for example, ProjectY_1) will be created.

Restoring a library as a shared library

This command restores the Soft-Import library, referenced by its ID, from the ProjectX_Daily archive into the Shared Libraries list of ProjectY:

$ flame_archive -r -F /home/ted/archives/projectX/ProjectX_Daily -S@H_1772839946_S_1744315218_U_242291 -P ProjectY -E "/Shared Libraries"

Restoring 1 entries
Processing entry 0 Soft-Import

Restoring a list of entries from a file

In this example, three entry IDs from ProjectX_Daily (a library, a folder, and a clip) are added to the id_list2.txt file. This file is then fed to flame_archive using the -B option and restored into the workspace libraries of ProjectY:
```
$ sh

sh$ tee /tmp/id_list2.txt << EOF
> @H_1772839946_S_1744315218_U_242291
> @H_1772839946_S_1744315218_U_243093
> @H_1772839946_S_1744315218_U_243271
> EOF

sh$ exit

$ flame_archive -r -F /home/ted/archives/projectX/ProjectX_Daily -B /tmp/id_list2.txt -P ProjectY -E "/Workspace/Libraries"
```
```
Restoring 3 entries
Processing entry 0 Soft-Import
Processing entry 1 FileSequences
Processing entry 2 Glow and Matchbox
```
Note: Project entries have restrictions on the types of entries they can contain. For example, a workspace cannot directly contain a library. In such cases, automatic conversions may occur. In this example, the FileSequences folder and the Glow and Matchbox clip were automatically placed into new libraries to meet these restrictions.

Tip: To avoid potential restoration issues caused by entry parenting restrictions, avoid mixing different entry types in a single entry list.

Converting an Archive

When upgrading to a newer Flame Family product version, archives created in older versions become read-only. To continue appending daily progress to an existing archive, you must convert it to the current format. The flame_archive tool provides a straightforward way to perform this conversion. A backup of the original archive header is created during the process to safeguard against interruptions or failures. However, any new content appended after the conversion will not be accessible using the backup.

Retrieving the version of an archive

The ArchInfo tool, located in the /opt/Autodesk/io/bin directory alongside flame_archive, can retrieve the version and metadata of an archive. This tool works with various catalog files, including archive headers, archive online table of contents (.otoc), clip libraries (.clib), and workspaces (.wks):

$ ls PBM_archive_test1{,*.seg}

PBM_archive_test1
PBM_archive_test1_10.seg
PBM_archive_test1_11.seg
...

$ ArchInfo PBM_archive_test1

DL Database: "PBM_archive_test1"
    Version:    2025.1 (0x2710)
    Features:    COMPRESSED_METADATA, AUDIO_DATA_422
    Format:        0xa000
    Metadata Size:    136012 (Compressed: 21356)
    Description:    Archive
    Comments:    Created 2024-03-26
    Created:    Tue Mar 26 11:10:34 2024
    Last modified:    Tue Apr  9 07:23:28 2024
    Block size:    1
    # of volumes:    31

Converting the archive

Converting an archive updates its header file to the current version. The .seg and .log files remain unaffected. Use the following command to perform the conversion:

$ flame_archive -c -F $PWD/PBM_archive_test1

$ ArchInfo PBM_archive_test1

DL Database: "PBM_archive_test1"
    Version:    2026 (0x2808)
    Features:    COMPRESSED_METADATA, AUDIO_DATA_422, MODIFIED_VERSION
    Format:        0xb000
    Metadata Size:    137110 (Compressed: 21351)
    Description:    Archive
    Comments:    Created 2024-03-26; [Converted from 2025.1 to 2026 on 2025-04-11 10:42:39 EDT by ted]
    Created:    Tue Mar 26 11:10:34 2024
    Last modified:    Fri Apr 11 10:42:39 2025
    Block size:    1
    # of volumes:    31

Reverting a converted archive

If an issue arises during or after the conversion, you can revert to the original archive header. The conversion process renames the original header with a .bkup. suffix. To revert, replace the current header with the backup:

$ mv PBM_archive_test1.bkup.2025.1 PBM_archive_test1

$ ArchInfo ./PBM_archive_test1

DL Database: "PBM_archive_test1"
    Version:    2025.1 (0x2710)
    Features:    COMPRESSED_METADATA, AUDIO_DATA_422
    Format:        0xa000
    Metadata Size:    136012 (Compressed: 21356)
    Description:    Archive
    Comments:    Created 2024-03-26
    Created:    Tue Mar 26 11:10:34 2024
    Last modified:    Tue Apr  9 07:23:28 2024
    Block size:    1
    # of volumes:    31

Note: Reverting an archive will discard any content added after the conversion, as the original header does not recognize these changes.

Command Line Archive & Restore

Modes of Operation

Creating an Archive

Retrieving Identifiers

Listing entries from a project

Listing entries from an archive

Selecting Entries

Selecting Within a Project

Examples

Selecting Within an Archive

Examples

Size Estimation

Archiving Entries

Restoring Entries

Converting an Archive

Was this information helpful?