Update-file-retention command

Only works in buckets with fileLockEnabled=true. Providing a retentionMode other than none requires providing retainUntil, which has to be a future timestamp in the form of an integer representing milliseconds since epoch.

If a file already is in governance mode, disabling retention or shortening it’s period requires providing --bypassGovernance.

If a file already is in compliance mode, disabling retention or shortening it’s period is impossible.


Setting file retention mode to ‘compliance’ is irreversible - such files can only be ever deleted after their retention period passes, regardless of keys (master or not) used. This is especially dangerous when setting bucket default retention, as it may lead to high storage costs.

In both cases prolonging the retention period is possible. Changing from governance to compliance is also supported.

Specifying the fileName is more efficient than leaving it out. If you omit the fileName, it requires an initial query to B2 to get the file name, before making the call to delete the file. This extra query requires the readFiles capability.

Requires capability:

  • writeFileRetentions

  • readFiles (if file name not provided)

and optionally:

  • bypassGovernance

b2 update-file-retention [-h] [--retainUntil TIMESTAMP] [--bypassGovernance]
                         [fileName] fileId {governance,compliance,none}

Positional Arguments


Possible choices: governance, compliance, none

Named Arguments


Default: False