p4 key

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

Syntax conventions

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:

  • p4 key name returns the value of key name.

  • 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.

  • p4 key -d name deletes the specified key.

  • 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.

  • 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 multi-server environments where running individual commands is likely to introduce unwanted latency.

  • p4 key --from oldvalue --to newvalue sets the specified key to the new value if the current value of the key is oldvalue. A key that is not 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.

For the minimal access level required to display and set keys, see Usage Notes and Examples.

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 namevalue ...

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.
If mykey does exist, its value is changed to the newly-specified value.

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.

Requires review access.

p4 key -m - mykey - mynewkey

Delete two keys.

Requires review access.

p4 key -m mykey 6 - mynewkey

Set one key; delete one key.

Requires review access.
p4 key --from=4 --to=6 mykey Set a different value for the key if the --from value is correct.

Related Commands

To list all keys and their values

p4 keys