Creating and Updating Records

Detailed documentation for record-add and record-update commands

Record-Add Command Documentation

This document provides comprehensive examples for creating records using the record-add command in Keeper Commander. The command supports dot notation for field specification and $JSON: syntax for complex field types.

Note: Keeper Commander supports line continuation using backslash (\) at the end of lines, allowing you to split long commands across multiple lines for better readability.

Important: Do not put spaces after the backslash (\) character. The line should end immediately with \ with no trailing spaces, otherwise empty arguments will be created and cause parsing errors.

Command Syntax

record-add --title "Record Title" --record-type "RECORD_TYPE" [OPTIONS] [FIELDS...]

Key Arguments

  • --title / -t: Record title (required)

  • --record-type / -rt: Record type (required)

  • --notes / -n: Record notes (optional)

  • --folder: Folder path or UID to store the record (optional)

  • --force / -f: Ignore warnings (optional)

  • --syntax-help: Display field syntax help

Field Syntax Overview

Dot Notation Format:

Components:

  • FIELD_SET: Optional. f (fields) or c (custom)

  • FIELD_TYPE: Field type (e.g., login, password, url, etc.)

  • FIELD_LABEL: Optional field label

  • FIELD_VALUE: The field value

Special Value Syntax:

  • $JSON:{"key": "value"} - For complex object fields

  • $GEN - Generate passwords, TOTP codes, or key pairs

  • file=@filename - File attachments

Record Types

Keeper Commander supports two types of records:

  1. Typed Records - Structured records with predefined schemas (login, bankAccount, contact, etc.)

  2. Legacy Records - General records (use -rt legacy or -rt general)

Field Types and Examples

Simple Field Types

  • login - Username/login field

  • password - Password field (masked)

  • url - Website URL

  • email - Email address

  • text - Plain text

  • multiline - Multi-line text

  • secret - Masked text field

  • note - Masked multiline text

  • oneTimeCode - TOTP/2FA codes

  • date - Unix epoch time or date strings

Complex Field Types (use $JSON:)

  • phone - Phone number with region/type

  • name - Person's name (first, middle, last)

  • address - Physical address

  • paymentCard - Credit card details

  • bankAccount - Bank account details

  • securityQuestion - Security Q&A pairs

  • host - Hostname/port combinations

  • keyPair - SSH key pairs

Quick Start Examples

Basic Login Record

Single-line version (safest for copy-paste):

Multi-line version (type manually, don't copy-paste):

Basic Contact with Phone

Scripting and working with multiple records

Keeper Commander allows scripting through run-batch or run commands. The easiest way to get the record JSON template is to create one record in web vault then in Keeper Commander run get UID --format=json that gives the exact format to use for complex object fields in the form $JSON:{"key": "value"} Then you can generate the batch script and run it.

Detailed Examples by Record Type

1. Login Records

2. Bank Account Records

3. Credit Card Records

4. Contact Records

5. Address Records

6. Server Credentials

7. SSH Keys

8. Software Licenses

9. WiFi Credentials

10. Secure Notes

11. Database Credentials

12. Driver's License

13. Passport

14. Health Insurance

15. Membership

16. Birth Certificate

17. Social Security Card

18. Photo Records

19. File Attachments

PAM (Privileged Access Management) Record Types

PAM records require additional commands to set them up for rotation, connections, tunneling etc. see the example below this section.

PAM Configuration types are created using pam config command.

20. PAM Database

21. PAM Directory

22. PAM Machine

23. PAM User

24. PAM Remote Browser

PAM Environment Example

Each PAM Record belongs to a PAM Configuration which references a Keeper Gateway usually installed in your local network or in a place that provides access to the PAM resources. The following is a good starting point for configuring a new PAM Environment.

Advanced Features

Password Generation

TOTP/2FA Generation

SSH Key Generation

Custom Fields

Common Field Reference

Date Formats

Phone Number Format

Name Format

Address Format

Security Questions Format

Self-Destructing Records (One-Time Shares)

The --self-destruct option creates temporary records that automatically delete themselves after being accessed. This is perfect for sharing sensitive information that should only be viewed once.

How Self-Destruct Works

  1. Creates a temporary shareable URL that expires after your specified time

  2. Record stays in your vault until someone opens the share URL

  3. Auto-deletes from your vault 5 minutes after the URL is first accessed

  4. Maximum duration is 6 months

Syntax

Time Units:

  • m or minutes - Minutes (default if no unit specified)

  • h or hours - Hours

  • d or days - Days

Examples

Share temporary password (expires in 1 hour):

One-time WiFi credentials (expires in 30 minutes):

Temporary file share (expires in 24 hours):

Emergency contact info (expires in 2 hours):

Return Value

When using --self-destruct, the command returns a shareable URL instead of a record UID:

Important Notes

⚠️ Security Considerations:

  • URL is the key - Anyone with the URL can access the record

  • No authentication required - Share URLs bypass login requirements

  • One-time access - Record deletes 5 minutes after first view

  • Cannot be recovered - Once deleted, the record is gone forever

⚠️ Limitations:

  • Maximum 6 months expiration time

  • Cannot update self-destructing records

  • No preview - You can't see the record again after creation

  • Immediate sharing - URL is active immediately upon creation

Best Practices

  1. Copy the URL immediately - You won't be able to retrieve it later

  2. Use short expiration times for maximum security (minutes/hours vs days)

  3. Include context in notes about why the record was created

  4. Share URL through secure channels (encrypted messaging, in person)

  5. Generate strong passwords using $GEN for temporary access

  6. Verify recipient received URL before the expiration time

Use Cases

  • Emergency access credentials for system administrators

  • Temporary passwords for contractors or consultants

  • One-time document sharing for sensitive files

  • Guest network credentials for visitors

  • Secure information handoffs between team members

  • Time-sensitive shared secrets for automated systems

Tips and Best Practices

  1. Use single-line commands for copy-paste to avoid trailing space issues

  2. Quote JSON values to prevent shell interpretation

  3. Use $GEN for passwords instead of hardcoding them

  4. Test with simple records first before creating complex ones

  5. Use custom fields (c.) for non-standard data

  6. Organize records in folders using the --folder parameter

  7. Add meaningful notes with --notes for context

Troubleshooting

Common Issues

"Expected: =, got: ; Missing ="

  • Remove trailing spaces after backslashes in multi-line commands

  • Use single-line format for copy-paste

"Field type not supported"

  • Check available field types with record-add --syntax-help

  • Use custom fields with c. prefix for non-standard fields

JSON parsing errors

  • Ensure JSON is properly quoted

  • Escape single quotes in JSON: '\''

  • Use double quotes inside JSON objects

File attachment errors

  • Use @ prefix: file=@/path/to/file.txt

  • Ensure file path is accessible

  • Use absolute paths to avoid confusion

Record-Update vs Record-Add

While record-add creates new records, record-update modifies existing records. Here's how they compare:

Key Differences

Feature
record-add
record-update

Purpose

Creates new records

Modifies existing records

Record identifier

Not required

Required (-r or --record)

Record type

Required (-rt)

Optional (can change type)

Field behavior

Sets all fields

Updates only specified fields

Notes behavior

Sets notes

Appends with + prefix, overwrites without

Record-Update Syntax

Key Arguments:

  • --record / -r: Record title or UID (required)

  • --title / -t: Update record title

  • --record-type / -rt: Change record type

  • --notes / -n: Update notes (+text appends, text overwrites)

  • --force / -f: Ignore warnings

Examples

Update password and URL:

Add a phone number to existing contact:

Append to notes (notice the + prefix):

Update title and add custom field:

Change record type (converts structure):

When to Use Each Command

Use record-add when:

  • Creating a completely new record

  • You want to specify all fields from scratch

  • Setting up initial record structure

Use record-update when:

  • Modifying existing records

  • Adding new fields to existing records

  • Updating passwords or other credentials

  • Appending information to notes

  • Converting between record types

Important Notes:

  • record-update only changes the fields you specify

  • Existing fields not mentioned remain unchanged

  • Use field= (empty value) to clear a field

  • Notes with + prefix append, without + they replace

Getting Help

PreviousRecord CommandsNextRecord Type Commands

Last updated

Was this helpful?