Commandline reference¶
You can control LocalSearch using the localsearch3 commandline tool. The various
subcommands are documented below.
This documentation is also available on your computer using the man command.
localsearch-3¶
Name
localsearch-3 — Filesystem indexer.
DESCRIPTION
localsearch-3 is not supposed to be run by the user since it is started by systemd when the user logs in. Of course, it can also be started manually for debugging purposes. You can not run more than one instance of this at the same time.
localsearch-3 mines information about applications and files only.
OPTIONS
- -?, --help
- Show summary of options.
- -V, --version
- Returns the version of this binary.
- -n, --no-daemon
- Tells the indexer to exit once all indexing has finished and the database is up to date. This is not the default mode of operation for the indexer, usually it stays around acting like a daemon to monitor file updates which may occur over time. This option renders the --initial-sleep option moot.
- -e, --eligible=FILE
- Checks if FILE is eligible for being mined based on the current configuration rules. In addition to this, it will check if FILE would be monitored for changes. This works with non-existing FILE arguments as well as existing FILE arguments.
DESKTOP INTEGRATION
Desktop environments that make use of localsearch-3 should start the localsearch-3.service user unit on startup. For instance, sessions managed by gnome-session can add this service as a Wants= dependency in their gnome-session@name.target.d/session.conf drop-in.
This allows sessions to disable background filesystem indexing (by simply not starting localsearch-3.service) in situations where it’s not necessary (i.e. special kiosk sessions)
localsearch-extract¶
Name
localsearch-extract — Show metadata extractor output.
DESCRIPTION
localsearch extract reads the file provided and extracts any metadata it can from this file, then displays the metadata on standard output.
The metadata is displayed as RDF data, equivalent to the data inserted in the indexer database relative to the extracted file metadata. This RDF data can feasibly be imported in a compatible triple store.
The actual metadata extraction is done by a separate sandboxed process.
OPTIONS
- -o, --output-format=<FORMAT>
- Choose which format to use to output results. Supported formats are turtle, trig and json-ld.
localsearch-index¶
Name
localsearch-index — List and change indexed folders
Synopsis
localsearch index localsearch index --add [--recursive] <dir> [[dir] ...] localsearch index --remove <path> [[dir] ...]
localsearch-info¶
Name
localsearch-info — Retrieve information available for files and resources.
DESCRIPTION
localsearch info asks for all the known metadata available for the given file.
Multiple file arguments can be provided to retrieve information about multiple files.
The file argument can be either a local path or a URI. It also does not have to be an absolute path.
OPTIONS
- -f, --full-namespaces
- By default, all keys and values reported about any given file are returned in shortened form, for example, nie:title is shown instead of http://tracker.api.gnome.org/ontology/v3/nie#title. This makes things much easier to see generally and the output is less cluttered. This option reverses that so FULL namespaces are shown instead.
- -c, --plain-text-content
- If the resource being displayed has nie:PlainTextContent (i.e. information about the content of the resource, which could be the contents of a file on the disk), then this option displays that in the output.
- -o, --output-format=<FORMAT>
- Choose which format to use to output results. Supported formats are turtle, trig and json-ld.
- -e, --eligible=<FILE>
- Checks whether a file is eligible for indexing. There might be a number of factors why it is not, e.g. being in a non-indexed folder, via configuration or filters.
localsearch-inhibit¶
Name
localsearch-inhibit — Inhibit indexing temporarily
localsearch-reset¶
Name
localsearch-reset — Erase the indexed data
DESCRIPTION
The reset command will change either your configuration or index irreversibly and should be used with care. Other than tags, actual data (e.g. files) should not be affected by this command.
The "index" is a link between your content (either locally or remotely) and how it can be found quickly using a number of different queries. Under the hood, this is done using a database.
Removing all data and starting again from the beginning with an empty data set (which is a common use of this command) will make LocalSearch behave as if it was just installed.
OPTIONS
- -s, --filesystem
- Removes indexed filesystem data. The indexer will automatically re-create its cache from the filesystem when it restarts. This option is the default if no arguments are given.
- -f, --file FILE
- Resets all indexed information about FILE, works recursively for directories. Nothing will be done if FILE is not currently indexed. After deletion, a request to reindex this data will be immediately issued.
localsearch-search¶
Name
localsearch-search — Search for content
DESCRIPTION
localsearch search searches all indexed content for the given search terms. Results are returned in ascending order.
- <search-terms>
One or more words to search for. When multiple terms are provided, the default operation is a logical AND. For logical OR operations, see -r.
If no search terms are supplied, then all items are returned.
Only resources which currently exist will be returned by this command (see --all for more information).
RESOURCE TYPES
- -f, --files
- Search for files of any type matching search-terms.
- -s, --folders
- Search for folders matching search-terms.
- -m, --music
- Search for music files matching search-terms.
- --music-albums
- Search for music albums matching search-terms.
- --music-artists
- Search for music artists matching search-terms.
- -i, --images
- Search for images matching search-terms.
- -v, --videos
- Search for videos matching search-terms.
- -t, --documents
- Search for documents matching search-terms.
- --software
- Search for software files matching search-terms.
OPTIONS
- -l, --limit=<limit>
- Limit search to limit results.
- -o, --offset=<offset>
- Offset the search results by offset. For example, start at item number 10 in the results. The default is 0.
- -d, --detailed
- Show the unique URN associated with each search result and a snippet of the matched search terms, if any was provided.
- -a, --all
- Show results which might not be available. This might bebecause a removable media is not mounted for example. Without this option, resources are only shown if they exist.
localsearch-status¶
Name
localsearch-status — Provide status and statistics on the data indexed
DESCRIPTION
Display the status of the current index and data set. A summary of recorded failures during file metadata indexing is also displayed.
Providing a search expression will list the full details of the recorded failures matching the filename.
With the --stat option, displays statistics about the RDF classes and how many of each exist for data set that has been indexed. For example, "10 Folders".
OPTIONS
- --stat
- List statistics of stored RDF classes (e.g. "nfo:Document" or "nfo:Folder") per graph.
- -f, --follow
- Follow status changes to daemons as they happen. This is a top level view of what is happening. You will see the name for each daemon and a state with the progress in that state. This requires Ctrl+C to stop and return to the command line.
- -w, --watch
- Watch changes that happen to the database in real time. This requires Ctrl+C to stop and return to the command line.
This option is implied if search terms are provided to filter ALL possible statistics.
localsearch-tag¶
Name
localsearch-tag — Add, remove and list tags.
Synopsis
localsearch tag FILE [-l <limit>] [-o <offset>] [-r] localsearch tag -t [-s] [-r] FILE localsearch tag -a <TAG> [-e <description>] localsearch tag -d <TAG>
DESCRIPTION
List tags for local files or by the tag labels themselves if -t is used.
It’s also possible to manage tags with the -a and and -d options.
The FILE argument can be either a local path or a URI. It also does not have to be an absolute path.
OPTIONS
- -t, --list
- List all tags. Results include the number of files associated with that tag and the tag’s unique identifier. You can show the files associated with each tag by using --show-files.
- -s, --show-files
- Show the files associated with each tag. This option is ONLY available WITH the --list option.
- -a, --add=TAG
- Add a tag with the name TAG. If no FILE argument is specified, the tag is simply created (if it didn’talready exist) and no files are associated with it.
- -d, --delete=TAG
- Delete a tag with the name TAG. If no FILE argument is specified, the tag is deleted for ALL files.
- -e, --description=STRING
- This option ONLY applies when using --add and provides a description to go with the tag label according to STRING.
- -l, --limit=N
- Limit search to N results. The default is 512.
- -o, --offset=N
- Offset the search results by N. For example, start at item number 10 in the results. The default is 0.
$ localsearch tag -s -t banana
Should show files in the database that have both the banana tag.
localsearch-writeback-3¶
Name
localsearch-writeback-3 — Metadata writeback service.
DESCRIPTION
localsearch-writeback is not supposed to be run by the user since it is started by its .desktop file when the user logs in. It can also be started manually of course for debugging purposes. You can not run more than one instance of this at the same time.
localsearch-writeback writes RDF metadata back into files. Currently support is limited to XMP metadata (which covers PNG, JPEG, TIFF, MP4 and 3GPP formats), play lists (which covers MPEGURL, SCPLS and IRIVER formats) and taglib supported mime types (which covers MP3, MP4, OGG, WAV, FLAC and some Windows media formats).