Tell Commands Reference

All commands follow the pattern:

> tell files <command> [arguments]

quit

> tell files quit

Gracefully stops the files add-in task. The Domino server continues running. Always run this before replacing the add-in binary.

create-db

> tell files create-db

Creates file_data.nsf and file_admin.nsf from their design templates if they do not already exist, then runs the RestrictAgentsToServer agent in each database to pin housekeeping agents to the current server. Run once on the primary server in a new deployment. In clustered environments, let replication distribute the databases to other servers.

migrate-config

> tell files migrate-config

Copies all recognised FILES_* settings from notes.ini into the Config profile document in file_admin.nsf, then removes those keys from notes.ini. After this command, the admin database becomes the active configuration source for all future startups. Also accessible via the Migrate Config button in the configuration form.

purge

> tell files purge

Triggers an immediate, out-of-schedule purge of trash items whose age exceeds TRASH_RETENTION_DAYS. Equivalent to running the housekeeping job early. Useful after bulk deletion or before reclaiming database space.

purge-expired-links

> tell files purge-expired-links

Immediately deletes all public share links that have passed their expiry date. Normally this runs as part of scheduled housekeeping; use this command to reclaim space or revoke access ahead of schedule.

search-sync

> tell files search-sync [--start-only]

Triggers an immediate synchronisation of the external search index with the current state of the data database. New, modified, and deleted documents are reconciled with the search service.

This is also how notes stamped failed_search — those that used up their indexing retries — are put back in the queue. On a database with a large backlog both the scan and the re-queue take a long time, so progress is reported as it goes (at debug — see Reading the search record processing log for how to enable it):

search-sync: scanning for notes stamped failed_search
search-sync: 68127 note(s) stamped failed_search; re-queueing
search-sync: 41000 of 68127 note(s) processed after 60s (41000 queued, 0 failed)
search-sync: queued 68127 of 68127 note(s) stamped failed_search in 97s (0 already queued, 0 failed); starting search sync

The re-queue only fills the queue; the indexing itself is reported separately as it runs — see Reading the search record processing log.

--start-only starts the sync thread without performing the cleanup phase. Useful for resuming a previously interrupted sync.

rebuild-search-index

> tell files rebuild-search-index <unid>
> tell files rebuild-search-index --all

Re-indexes a single file by UNID, or rebuilds the entire search index with --all.

Single-file reindex:

> tell files rebuild-search-index 8A2B3C4D5E6F7890AABBCCDD11223344
Queued file 8A2B3C4D5E6F7890AABBCCDD11223344 for search reindexing

This creates a new search record for the file, which the search worker will process — indexing metadata and uploading file content for full-text extraction. If the UNID does not exist or refers to a folder (not a file), an appropriate warning is logged.

Full rebuild:

> tell files rebuild-search-index --all

Drops and rebuilds the external search index from scratch by re-indexing all documents in the data database. Use this after a major data migration or if the search index becomes inconsistent. This operation may be time-consuming on large databases.

Note: The --all flag is required for a full rebuild to prevent accidental triggers.

search-status

> tell files search-status

Prints the current status of the search index to the Domino console, including synchronisation state and any pending work.

delete-search-records

> tell files delete-search-records <state>

Deletes queued search records in the given state from the indexing queue. This is a manual escape hatch for a queue that has become wedged — for example, records endlessly looping in failing_upload and never draining. Run search-status first to see how many records are in each state.

<state> is one of the queue states, or all:

Issue the command without a <state> to print the accepted states.

Dequeues only — leaves the search index incomplete. Deleting a search record removes the document from the indexing pipeline. It does not touch the external search server, does not re-index, and — unlike the pipeline's own give-up path — does not stamp the file note failed_search. Two consequences to understand before running it:

• The document's search data will be incomplete. In new and failing_index, metadata indexing never completed, so the document is missing from the search index entirely. In pending_upload and failing_upload, metadata has been indexed but the content upload never completed, so the document is searchable by metadata only — no extracted full text.
• The document is not re-queued automatically. Because the file note is not stamped failed_search, search-sync will not pick it back up — it only re-queues notes stamped failed_search. (Not stamping it is intentional: stamping would let the failed_search re-queue immediately recreate the very records you deleted, defeating the escape hatch.) To re-index afterwards, run rebuild-search-index to rebuild the whole index; a single document is also re-queued the next time its file is modified.

The command reports how many records it deleted. An unrecognised <state> is rejected without deleting anything.

Example:

> tell files delete-search-records failing_upload
Deleted 412 search record(s) in state 'failing_upload'.

delete-thumbnail-records

> tell files delete-thumbnail-records <state>

Deletes queued thumbnail records in the given state from the thumbnail-generation queue — the same manual escape hatch as delete-search-records, but for the thumbnail queue. Use it when thumbnail generation has become wedged on a state.

<state> is one of the queue states, or all:

Issue the command without a <state> to print the accepted states.

Dequeues only. Deleting a thumbnail record removes it from the generation pipeline. It does not delete any thumbnails that were already generated, and it does not regenerate anything. Deleting a record whose file was mid-generation also does not clear that file's thumbnail_status, so a file left in processing keeps showing "processing" to clients until it is re-queued. To regenerate, modify the file again — a thumbnail is re-queued the next time its file is created or updated.

The command reports how many records it deleted. An unrecognised <state> is rejected without deleting anything.

Example:

> tell files delete-thumbnail-records failing
Deleted 27 thumbnail record(s) in state 'failing'.

storage-report

> tell files storage-report [--limit <n>] [--output <console|db>]

Generates a storage usage report showing per-user quota consumption.

migrate-version-modifiers

> tell files migrate-version-modifiers [--dry-run]

Migrates legacy per-version modified_<millis> modifier items on File notes to the current fixed-name format (version_modifier_ts / version_modifier_dn). This is a one-time migration operation for environments upgraded from an older release.

--dry-run reports how many notes would be migrated without making any changes.

After a successful migration, run a copy-style compact on the data database to reclaim the space freed by the removed legacy items.

delete-user-data-dryrun

> tell files delete-user-data-dryrun <user_dn>

Read-only. Reports all Files content owned by the specified user (files, folders, shares, access requests, etc.) without deleting anything. Use this to review what would be removed before running the destructive delete-user-data command.

User DNs containing spaces do not need to be quoted (the Domino console strips quotes; the add-in reassembles the tokens into a single DN).

Example:

> tell files delete-user-data-dryrun CN=John Doe/O=Acme

delete-user-data

> tell files delete-user-data <user_dn>

Irreversible. Permanently deletes all Files content owned by the specified user. Intended for GDPR / right-to-erasure compliance workflows. Always run delete-user-data-dryrun first to confirm the scope of the deletion.

Example:

> tell files delete-user-data CN=John Doe/O=Acme

logout

> tell files logout <session_id>

Invalidates the specified OIDC session (identified by its SID). This command is used internally by the backchannel logout broadcast mechanism to propagate logout events across clustered servers. It can also be issued manually to forcibly end a user session.