Ctrlk
HomepageSystem Status

Nested Share Subfolder Commands

All the commands related to Nested Share Subfolder records and folders

Commands

With the introduction of Nested Share Subfolders with Role-Based Folder Permissions, we’ve rebuilt the vault’s folder, sharing and permissions model from the ground up, delivering a more flexible and scalable experience for every user and team.

During this transition, the new Nested Share Subfolder system will exist alongside the existing Classic folder system and permission model, with two distinct folder icons to help users easily differentiate between them.

Nested Share Subfolders is built on the Keeper v3 API. The commands listed below operate exclusively on Nested Share folders and records and use the nsf- prefix to keep them clearly separated from the classic vault commands.

Whether using the interactive shell, CLI or JSON config file, Keeper supports the following Nested Share Subfolder commands. Each command supports additional parameters and options.

To get help on a particular command, run:

help <command>

nsf-list

List Nested share folders and records

nsf-get

Show the details of a Nested share record or folder

nsf-record-details

Show metadata (title, type, version, revision) for one or more records

nsf-mkdir

Create a Nested share folder

nsf-rndir

Rename or recolor a Nested share folder

nsf-rmdir

Remove a Nested share folder and its entire contents

nsf-record-add

Create a Nested share record

nsf-record-update

Update an existing Nested share record

nsf-rm

Remove (trash, permanently delete, or unlink) a Nested share record

nsf-ln

Link a record into a Nested share folder

nsf-shortcut

List or manage Nested share record shortcuts (records in 2+ folders)

nsf-share-folder

Grant or revoke folder sharing

nsf-share-record

Grant, update, revoke, or transfer ownership of a record share

nsf-record-permission

Bulk-update record sharing permissions for every record inside a folder

nsf-transfer-record

Transfer record ownership to another user

nsf-list command

Command: nsf-list

Detail: List Nested share folders and records cached locally. By default, both folders and records are shown. Use the --folders or --records flag to filter, and --format to control the output style.

Switches:

--folders show only folders

--records show only records

--format <{table, csv, json}> choose the format of the output

  • table — show the result in table format (default)

  • csv — show the result in CSV format

  • json — show the result in JSON format

--output <FILENAME> path to the resulting output file (ignored for table format)

Examples:

  1. List every Nested share folder and record

  2. List only Nested share folders

  3. Show all Nested share records in JSON format

  4. Export the full Nested share listing to a CSV file

nsf-get command

Command: nsf-get

Detail: Show the details of a Nested share record or folder by UID or title. The command first attempts to resolve the input as a folder and falls back to record resolution. For records it prints field values and per-user permissions; for folders it prints user/team permissions and any share administrators.

Parameters:

UID or title of a Nested share record or folder

Switches:

--format <{detail, json}> choose the format of the output

  • detail — human-readable report (default)

  • json — machine-readable JSON

-v, --verbose show the full permission breakdown for each accessor (per-flag)

--unmask reveal masked field values (passwords, secrets, PINs). Output is sent to stdout only and is never written to log files.

Examples:

  1. Show the details of a Nested share object (record or folder) by UID

  2. Show the details of a Nested share folder by name

  3. Show the details of a record in JSON format

  4. Show the record details with masked fields revealed in plain text

  5. Show the record details with the full per-flag permission breakdown

--unmask displays sensitive data (passwords, secrets) on the terminal. Make sure you are in a safe environment before using this flag.

nsf-record-details command

Command: nsf-record-details

Detail: Retrieve metadata (title, type, version, revision) for one or more Nested share records using the v3 API. Useful for quickly inspecting record attributes without dumping field values.

Parameters:

One or more record UIDs (or titles, which are resolved to UIDs)

Switches:

--format <{table, json}> choose the format of the output

  • table — human-readable text (default)

  • json — JSON output

Examples:

  1. Show metadata for a single record

  2. Show metadata for multiple records in one call

  3. Output record metadata as JSON

nsf-mkdir command

Command: nsf-mkdir

Detail: Create a new Nested share folder using the v3 API. The folder is created as a child of the current folder when the user is cd-ed into a Nested share folder; otherwise it is created at the Nested share folder root.

Parameters:

Folder name (use // to embed a literal / in the name; nested paths are not supported — nsf-mkdir creates exactly one folder per call).

Switches:

--color <{none, red, orange, yellow, green, blue, gray}> set the folder colour

--no-inherit do not inherit parent folder permissions (the new folder will start with no shares)

Examples:

  1. Create a folder named "Engineering" under the current location

  2. Create a blue-coloured folder named "Q1 Reports"

  3. Create a folder that does not inherit parent folder permissions

  4. Create a folder whose literal name contains a forward slash: Side/Project

If a folder with the same name already exists in the same parent location, nsf-mkdir will not create a duplicate; it logs a warning and returns the existing folder UID.

nsf-rndir command

Command: nsf-rndir

Detail: Rename a Nested share folder, change its colour, or update its parent-permission inheritance setting. At least one of --name, --color, --inherit, or --no-inherit must be supplied.

Parameters:

Path or UID of an existing Nested share folder

Switches:

-n, --name <NAME> new folder name

--color <{none, red, orange, yellow, green, blue, gray}> set/change folder color

-q, --quiet suppress the post-rename confirmation message

Examples:

  1. Rename a folder

  2. Change a folder's colour by UID

  3. Rename and recolour a folder in a single call

nsf-rmdir command

Command: nsf-rmdir

Detail: Remove one or more Nested share folders and their entire contents. The command always runs a preview first (showing the impact: sub-folders, records, affected users and teams) before asking for confirmation. Up to 100 folders may be removed per invocation.

Parameters:

One or more folder UID(s) or name(s)

Switches:

--operation, -o <{folder-trash, delete-permanent}> removal operation (default: folder-trash)

  • folder-trash — recoverable; folders go to the trash

  • delete-permanent — IRREVERSIBLE; folders and their contents are permanently destroyed

--force, -f skip the confirmation prompt and execute immediately after the preview

--dry-run run the preview step only; do not delete anything (mutually exclusive with --force)

--quiet, -q suppress per-folder detail; only show the summary

Examples:

  1. Move the "Engineering" folder to the trash (with confirmation)

  2. Trash a folder by UID without prompting

  3. Trash multiple folders in a single call

  4. Permanently delete a folder and all its contents (IRREVERSIBLE)

  5. Preview the impact of removing a folder without actually deleting it

--operation delete-permanent cannot be undone. All sub-folders and records inside the targeted folder(s) will be permanently destroyed.

nsf-record-add command

Command: nsf-record-add

Detail: Create a new Nested share record. Mirrors the "classic" record-add command and supports all standard record types, custom record types, standard fields, and custom fields. Use --syntax-help for detailed examples of field specifications.

Parameters:

A space-separated list of field values using the standard field syntax: <FIELD_NAME>=<FIELD_VALUE>. See --syntax-help for full details.

Switches:

-t, --title <TITLE> record title (required)

-rt, --record-type <TYPE> record type (required); see the list of standard record types

-n, --notes <NOTES> record notes

--folder <FOLDER> folder name or UID to store the new record in (omit to place at the Nested share root)

-f, --force ignore warnings (e.g. unsupported attachment fields) and create the record anyway

--syntax-help display detailed information on field syntax and exit

Examples:

  1. Create a login record in the "Engineering" folder with a generated password

  2. Create an empty "classic" record at the Nested share Folder root

  3. Show the field-syntax help and exit

File attachments are not yet supported in nsf-record-add. Use the classic record-add command if you need to attach files.

nsf-record-update command

Command: nsf-record-update

Detail: Update an existing Nested share record. Title, notes, record type, and individual fields can all be modified. Multiple records can be updated in a single invocation by supplying -r more than once.

Parameters:

A space-separated list of field values using the standard field syntax: <FIELD_NAME>=<FIELD_VALUE>.

Switches:

-r, --record <RECORD> record path or UID to update (required, repeatable)

-t, --title <TITLE> modify the record title

-rt, --record-type <TYPE> change the record type

-n, --notes <NOTES> append/modify the record notes

-f, --force ignore warnings

--syntax-help display detailed information on field syntax and exit

Examples:

  1. Rename a record

  2. Replace the password on a record (regenerate using $GEN)

  3. Update notes on multiple records in one call

  4. Show the field-syntax help

nsf-rm command

Command: nsf-rm

Detail: Remove one or more Nested share records. Always runs a preview first (showing the impact: folders, additional locations, affected users/teams) and asks for confirmation. Up to 500 records may be removed per invocation. Three removal operations are supported.

Parameters:

One or more record UID(s) or title(s)

Switches:

--folder <FOLDER> folder UID or name that provides the context for the removal (required when --operation unlink is used)

--operation, -o <{owner-trash, folder-trash, unlink}> removal operation (default: owner-trash)

  • owner-trash — only the owner deletes the record; it lands in the owner's trash

  • folder-trash — remove the record from the supplied folder context and trash it

  • unlink — remove the record from a specific folder only; the record itself remains in other folders (requires --folder)

--force, -f skip the confirmation prompt and execute immediately after the preview

--dry-run run the preview only (mutually exclusive with --force)

Examples:

  1. Move the record to the owner's trash (with confirmation)

  2. Force-delete a record by title without prompting

  3. Remove multiple records in one call

  4. Unlink a record from the "Engineering" folder while leaving it in any other folders it appears in

  5. Preview a removal without actually deleting

nsf-ln command

Command: nsf-ln

Detail: Link an existing Nested share record into a Nested share folder. The record will appear in both its original folder(s) and the destination folder (similar to a hard-link).

Parameters:

Two positional arguments: RECORD FOLDER

  • RECORD — record UID, title, or path

  • FOLDER — destination folder UID or name

Examples:

  1. Link a record (by UID) into the "Engineering" folder

  2. Link a record (by title) into the "Marketing" folder

  3. Link a record into the Nested share root

nsf-shortcut command

Command: nsf-shortcut <subcommand>

Detail: List or manage Nested share record shortcuts. A "shortcut" exists when the same record is linked into more than one folder.

Sub-commands:

  • list <RECORD UID, FOLDER UID, or PATH> — show records that appear in 2+ folders, optionally filtered by record or folder

  • keep <RECORD> <FOLDER> — keep the record in exactly one folder; remove all other shortcuts

nsf-shortcut list

Switches:

--format <{table, csv, json}> choose the format of the output (default: table)

--output <FILENAME> file to write output results to

Examples:

  1. Display every record that appears in more than one folder

  2. Export the shortcut list to a CSV file

  3. Show only the shortcuts for a specific record (by UID)

  4. Show only the shortcut records that exist in the "Engineering" folder

nsf-shortcut keep

Switches:

-f, --force do not prompt before removing the extra shortcuts

Examples:

  1. Keep "API Key" only in the "Engineering" folder; remove it from all other folders (with confirmation)

  2. Keep a record only in the "Production" folder without prompting

  3. Keep a record only in the current folder (when no folder is specified, the current folder is used; you must be cd-ed into a Nested share folder)

nsf-shortcut keep only removes the links — the record itself is preserved in the folder you choose to keep it in.

nsf-share-folder command

Command: nsf-share-folder

Detail: Grant or revoke sharing on one or more Nested share folders. Supports user emails, team names/UIDs, and the special @existing recipient that expands to all users and teams currently on the folder (excluding the caller).

Parameters:

One or more folder paths or UIDs (positional, repeatable)

Switches:

-a, --action <{grant, remove}> share-folder action (default: grant). grant also updates existing shares.

-e, --email <USER> recipient — account email, team name, team UID, or @existing for all users and teams currently on the folder (repeatable)

-r, --role <ROLE> permission role (default: viewer). Required for grant. Allowed values:

  • viewer

  • share-manager

  • content-manager

  • content-share-manager

  • full-manager

--expire-at <TIMESTAMP> share expiration as never or ISO datetime (e.g. 2027-01-01T00:00:00Z)

--expire-in <PERIOD> share expiration as never or a relative period (e.g. 30d, 6mo, 1y, 24h, 30mi)

Examples:

  1. Grant viewer access to a single user

  2. Grant content-manager access to multiple users in one call

  3. Grant full-manager access to a team (by team name)

  4. Grant viewer access that automatically expires in 30 days

  5. Remove a single user from the folder

  6. Remove every existing user and team from the folder (excluding the caller)

--expire-at and --expire-in are mutually exclusive.

nsf-share-record command

Command: nsf-share-record

Detail: Manage Nested share record sharing. Supports granting, updating, revoking, and transferring ownership. The record argument can be a record UID, a record title, or a folder (in which case all records inside the folder are processed; combine with -R for recursive descent).

Parameters:

A record path/UID or a folder path/UID (positional)

Switches:

-e, --email <EMAIL> recipient email (required, repeatable)

-a, --action <{grant, revoke, owner}> sharing action (default: grant)

  • grant — share the record (also updates existing shares)

  • revoke — remove the share

  • owner — transfer record ownership (single recipient only)

-r, --role <ROLE> permission role; required for grant. Allowed values: viewer, share-manager, content-manager, content-share-manager, full-manager

-R, --recursive apply the command to every record within the folder and its sub-folders

--contacts-only only share with already-known contacts (refuses unknown email addresses unless --force is supplied)

-f, --force skip confirmation prompts (e.g. for --contacts-only confirmations)

--dry-run display the permission changes without committing them

--expire-at <EXPIRE_AT> share expiration as never or UTC datetime (e.g. 2027-01-01T00:00:00Z)

--expire-in <PERIOD> share expiration as never or a relative period (e.g. 30d, 6mo, 1y)

Examples:

  1. Share a record with a single user as a viewer

  2. Share a record with multiple users in one call

  3. Share every record in the "Engineering" folder and its sub-folders with a single user

  4. Share a record with an expiration of 30 days

  5. Revoke a share

  6. Transfer ownership of a record (you will lose access after the transfer completes)

  7. Preview a share without committing the change

-a owner transfers record ownership — you will no longer have access to the record once the transfer is accepted. Only one recipient is allowed.

nsf-record-permission command

Command: nsf-record-permission

Detail: Bulk-update sharing permissions for every record in a Nested share folder. Useful for normalizing permissions across an entire folder (e.g. "make every share in the Production folder a viewer"). Permissions inherited from a parent shared folder are also handled — a fresh direct share is created to override an inherited row.

Parameters:

Folder path or folder UID (positional, optional — defaults to the Nested share folder root)

Switches:

-a, --action <{grant, revoke}> action to perform (required)

  • grant — set every applicable share to --role

  • revoke — remove every applicable share (or only those matching --role if supplied)

-r, --role <ROLE> role to grant, or filter to revoke. Allowed values: viewer, share-manager, content-manager, content-share-manager, full-manager

-R, --recursive apply the change to every record in the folder and its sub-folders

--dry-run display the permission changes without committing them

-f, --force apply changes without confirmation

Examples:

  1. Set every record share in the "Engineering" folder to viewer

  2. Set every record share in "Engineering" and its sub-folders to content-manager

  3. Revoke every non-owner share on every record in "Engineering"

  4. Revoke only the viewer shares on records in "Engineering"

  5. Preview the planned permission changes without committing them

  6. Apply the change without confirmation

Shares inherited from a parent shared folder cannot be revoked at the record level — they must be removed from the parent shared folder instead. The command will list any such shares as skipped.

nsf-transfer-record command

Command: nsf-transfer-record

Detail: Transfer ownership of one or more Nested share records to another user. After a successful transfer, the original owner loses access to the record(s). For finer-grained control, see nsf-share-record -a owner.

Parameters:

Two positional arguments: RECORD_UIDS... NEW_OWNER_EMAIL

  • one or more record UIDs (or titles), followed by

  • the new owner's email address

Examples:

  1. Transfer ownership of a record to another user

  2. Transfer ownership of multiple records to the same new owner

After ownership is transferred you will no longer have access to the record. Make sure the new owner is correct before running this command.

Roles reference

Several Nested share sharing commands accept a --role option. The available roles are listed below in order of increasing privilege:

Role
Description

viewer

Read-only access to records

share-manager

Can manage who else has access (cannot edit content)

content-manager

Can edit record content (cannot manage shares)

content-share-manager

Can edit record content and manage shares

full-manager

Full control: edit, share, and delegate. Equivalent to a Share Administrator on the record/folder.

Operation reference

nsf-rm and nsf-rmdir accept an --operation flag that determines how the removal is performed:

Operation
Applies to
Description

owner-trash

nsf-rm (default)

Owner-only deletion — record goes to the owner's trash

folder-trash

nsf-rm, nsf-rmdir (default for folders)

Removes the record/folder from the supplied folder context and trashes it; recoverable from trash

unlink

nsf-rm

Removes the record from the specified folder only; the record itself stays in any other folders

delete-permanent

nsf-rmdir

IRREVERSIBLE — folder and all contents are permanently destroyed

PreviousCommand ReferenceNextImport and Export Data

Last updated