p4 key

Synopsis

Display, set, or delete a key/value pair.

Syntax

p4 [g-opts] key name
p4 [g-opts] key [-v]name value
p4 [g-opts] key [-d] name
p4 [g-opts] key [-i -v] name
p4 [g-opts] key [-m] [pair list]
p4 [g-opts] key --from oldvalue --to newvalue name

Description

Keys allow you to store name-value pairs for use in scripts. These user-managed keys are stored in a table named db.nameval.

The command includes the following variants:

  • The variant p4 key name returns the value of key name.

  • The variant p4 key name value sets the value of the key name to value, and if name does not already exist, it is created.

    Specifying -v displays the previous value of the specified key after the key has been set or incremented.

  • The variant p4 key -d name deletes the specified key.

  • The variant p4 key -i name increments a numeric key.

    Specifying -v displays the previous value of the specified key after the key has been set or incremented.

  • The variant p4 key [-m] pair list defines multiple set and delete operations to be performed. Each operation is defined by a value pair in the pair list. To set a key, use a name and value, to delete a key, use a - (hyphen) followed by the name. See Examples.

    This variant is useful in distributed environments where running individual commands is likely to introduce unwanted latency.

  • The final variant (--from …​ --to) sets the specified key to the new value only if the current value of the key is oldvalue. A key that has never been set or that has been deleted cannot be set using this syntax variant.

If a key does not exist, its value is returned as zero; key names are not stored until set to a nonzero value.

If the dm.keys.hide configurable is set to 2, admin access is required.

Options

-d name

Delete key name from the Perforce service.

-i name

Increment key name by 1 and return the new value. This option can only be used with numeric keys.

-m name value ...

Perform multiple key value operations in one command. See Examples.

g-opts

See “Global Options”.

Usage Notes

Can File Arguments Use Revision Specifier? Can File Arguments Use Revision Range? Minimal Access Level Required

N/A

N/A

list to display a key’s value;
(admin if dm.keys.hide is set to 2)
review to set a new value

Examples

p4 key mykey 12

Set the value of mykey to 12. If mykey does not exist, it is created.

Requires review access.

p4 key mykey

Display the value of mykey. If mykey does not exist, its value is displayed as 0.

Requires list access.

p4 key -m mykey 5 mynewkey 4

Set two keys.

p4 key -m - mykey - mynewkey

Delete two keys.

p4 key -m mykey 6 - mynewkey

Set one key; delete one key.

Related Commands

To list all keys and their values

p4 keys