Commands

In vimiv all keybindings are mapped to commands.

Most of the commands can also be run from the command line but some are hidden as they are not useful to run by hand. A typical example is the :command command which enters the command line.

Every command is limited to its mode. This allows commands with equal names to do different things depending on the mode they are run in. For example the :zoom command rescales the image in image mode but changes the size of thumbnails in thumbnail mode. This also prevents running commands that are useless in the current mode. Commands available in the special global mode can be run in image, library and thumbnail mode.

Below is a complete list of all commands in every mode.

Global

Overview of global commands

Command

Description

alias

Add an alias for a command.

bind

Bind keys to a command.

command

Enter command mode.

copy-image

Copy currently selected image to system clipboard.

copy-name

Copy name of current path to system clipboard.

delete

Move one or more images to the trash directory.

enter

Enter another mode.

fullscreen

Toggle fullscreen mode.

help

Show help on a command or setting.

history-clear

Clear the command history.

keybindings

Show a pop-up with keybindings information.

log

Log a message with the corresponding log level.

mark

Mark one or more paths.

mark-clear

Clear all marks.

mark-rename

Rename marked images with a common base.

mark-restore

Restore the last cleared marks.

next

Select next image.

nop

Do nothing.

open

Open one or more paths.

paste-name

Paste path from clipboard to open command.

prev

Select previous image.

print-stdout

Print text to the terminal.

quit

Quit vimiv.

rename

Rename images with a common base.

repeat-command

Repeat the last command.

scale

Scale the image.

search

Start a search.

search-next

Continue search to the next match.

search-prev

Continue search to the previous match.

set

Set an option.

sleep

Sleep for a given number of seconds.

spawn

Spawn a command in a sub-shell.

tag-delete

Delete an existing tag.

tag-load

Load images from a tag into the current mark list.

tag-open

Open images from a tag in image mode.

tag-write

Write marked paths to a tag.

toggle

Toggle one mode.

unbind

Unbind a keybinding.

undelete

Restore a file from the trash directory.

version

Show a pop-up with version information.

welcome-to-qt

Show a pop-up with a welcome message for users coming from gtk.

alias

Add an alias for a command.

syntax: :alias name command [--mode=MODE]

The command can be a vimiv command like quit or an external shell command like !gimp.

positional arguments:
  • name: Name of the newly defined alias.

  • command: Name of the command to alias.

optional arguments:
  • --mode: Mode in which the alias is valid. Default: global.

bind

Bind keys to a command.

syntax: :bind keybinding command [--mode=MODE]

positional arguments:
  • keybinding: The keys to bind.

  • command: The command to execute with optional arguments.

optional arguments:
  • --mode: The mode to bind the keybinding in. Default: current.

command

Enter command mode.

syntax: :command [--text=TEXT]

optional arguments:
  • --text: String to append to the : prefix.

copy-image

Copy currently selected image to system clipboard.

syntax: :copy-image [--primary] [--width=WIDTH] [--height=HEIGHT] [--size=SIZE]

optional arguments:
  • --primary: Copy to primary selection.

  • --width: Scale width to the specified value.

  • --height: Scale height to the specified value.

  • --size: Scale longer side to the specified value.

count: Equivalent to the --size option

copy-name

Copy name of current path to system clipboard.

syntax: :copy-name [--abspath] [--primary]

optional arguments:
  • --abspath: Copy absolute path instead of basename.

  • --primary: Copy to primary selection.

delete

Move one or more images to the trash directory.

syntax: :delete path [path ...]

positional arguments:
  • paths: The path(s) to the images to delete.

optional arguments:
  • --ask: Prompt for confirmation before deleting the images.

Note

This only deletes images, not any other path(s).

enter

Enter another mode.

syntax: :enter mode

positional arguments:
  • mode: The mode to enter (image/library/thumbnail/manipulate).

fullscreen

Toggle fullscreen mode.

help

Show help on a command or setting.

syntax: :help topic

positional arguments:
  • topic: Either a valid :command or a valid setting name.

Hint

For commands help :command is the same as command -h.

history-clear

Clear the command history.

This clears the history of all modes unless --mode is passed.

syntax: :history-clear [--mode]

optional arguments:
  • --mode: Clear the history of the current mode only.

keybindings

Show a pop-up with keybindings information.

syntax: :keybindings [--columns=N]

optional arguments:
  • --columns: Number of columns to split the bindings in.

log

Log a message with the corresponding log level.

syntax: :log level message

positional arguments:
  • level: Log level of the message (debug, info, warning, error, critical).

  • message: Message to log.

mark

Mark one or more paths.

syntax: :mark path [path ...] [--action=ACTION]

Hint

:mark % marks the current path.

positional arguments:
  • paths: The path(s) to mark.

optional arguments:
  • --action: One of toggle/mark/unmark. Toggle, the default, inverses the mark status of the path(s). Mark forces marking while unmark forces removing the mark.

mark-clear

Clear all marks.

Hint

It is possible to restore the last cleared marks using mark-restore.

mark-rename

Rename marked images with a common base.

syntax: :mark-rename base [--start=INDEX] [--separator=SEPARATOR] [--overwrite] [--skip-image-check]

Example::

:mark-rename my_mark would rename all marked images to my_mark_001, my_mark_002, …, my_mark_NNN.

positional arguments:
  • paths: The path(s) to rename.

  • base: Base name to use for numbering.

optional arguments:
  • --start: Index to start numbering with. Default: 1.

  • --separator: Separator between base and numbers. Default: ‘_’.

  • --overwrite: Overwrite existing paths when renaming.

  • --skip-image-check: Do not check if all renamed paths are images.

mark-restore

Restore the last cleared marks.

next

Select next image.

syntax: :next [--keep-zoom]

optional arguments:
  • --keep-zoom: Keep zoom level and scroll position of the current image.

count: multiplier

nop

Do nothing.

This is useful to remove keys bound by Qt by explicitly binding them to nop.

open

Open one or more paths.

syntax: :open path [path ...]

If any path given is an image, all valid images are opened in image mode. Otherwise the first valid directory is opened. If both fails, an error is displayed.

positional arguments:
  • paths: The path(s) to open.

paste-name

Paste path from clipboard to open command.

syntax: :paste-name [--primary]

optional arguments:
  • --primary: Paste from primary selection.

prev

Select previous image.

syntax: :prev [--keep-zoom]

optional arguments:
  • --keep-zoom: Keep zoom level and scroll position of the current image.

count: multiplier

quit

Quit vimiv.

rename

Rename images with a common base.

syntax: :rename path [path ...] base [--start=INDEX] [--separator=SEPARATOR] [--overwrite] [--skip-image-check]

Example::

:rename * identifier would rename all images in the filelist to identifier_001, identifier_002, …, identifier_NNN.

positional arguments:
  • paths: The path(s) to rename.

  • base: Base name to use for numbering.

optional arguments:
  • --start: Index to start numbering with. Default: 1.

  • --separator: Separator between base and numbers. Default: ‘_’.

  • --overwrite: Overwrite existing paths when renaming.

  • --skip-image-check: Do not check if all renamed paths are images.

repeat-command

Repeat the last command.

count: Repeat count times.

scale

Scale the image.

syntax: :scale [--level=LEVEL]

count: If level is a float, multiply by count.

optional arguments:
  • --level: The level to scale the image to.

Hint

supported levels:

  • fit: Fit image to current viewport.

  • fit-width: Fit image width to current viewport.

  • fit-height: Fit image height to current viewport.

  • overzoom: Like fit but limit to the overzoom setting.

  • float: Set scale to arbitrary decimal value.

search-next

Continue search to the next match.

syntax: :search-next

count: multiplier

search-prev

Continue search to the previous match.

syntax: :search-next

count: multiplier

set

Set an option.

syntax: :set name [value]

positional arguments:
  • name: Name of the setting to set.

  • value: Value to set the setting to. If not given, set to default.

sleep

Sleep for a given number of seconds.

syntax: :sleep duration

positional arguments:
  • duration: The number of seconds to sleep.

spawn

Spawn a command in a sub-shell.

syntax: :spawn command [--shell=shell --shellarg=shellarg]

positional arguments:
  • command: Full command with arguments to pass to the shell.

optional arguments:
  • --shell: The program to use as sub-shell. Default: sh.

  • --shellarg: Argument to prepend for the shell. Default: -c.

The difference to running commands with ! is that an actual shell is involved instead of running the program directly. This means that shell, redirection etc. will work in spawn, but not with !. Nevertheless ! is recommended in general for performance and security reasons.

tag-delete

Delete an existing tag.

syntax: :tag-delete name

Warning

If you pass a tag group directory, the complete tree is deleted.

positional arguments:
  • name: Name of the tag to delete.

tag-load

Load images from a tag into the current mark list.

syntax: tag-load name

Hint

You can open all marked images with :open %m.

positional arguments:
  • name: Name of the tag to load.

tag-open

Open images from a tag in image mode.

syntax: tag-open name

Hint

This is equivalent to :tag-load name && open %m.

positional arguments:
  • name: Name of the tag to open.

tag-write

Write marked paths to a tag.

syntax: :tag-write name

This writes all currently marked images to this tag. This allows storing a selection of marked images under a name and re-loading them in later sessions using :tag-load name. If the tag file exists, all marked paths that are not in the tag are appended to it.

Hint

It is possible to group tags into directories by dividing the name into a directory tree, e.g. :tag-write favourites/2017.

positional arguments:
  • name: Name of the tag to create.

toggle

Toggle one mode.

syntax: :toggle mode.

If the mode is currently visible, leave it. Otherwise enter it.

positional arguments:
  • mode: The mode to toggle (image/library/thumbnail/manipulate).

unbind

Unbind a keybinding.

syntax: :unbind keybinding [--mode=MODE]

positional arguments:
  • keybinding: The keybinding to unbind.

optional arguments:
  • --mode: The mode to unbind the keybinding in. Default: current.

undelete

Restore a file from the trash directory.

syntax: :undelete [basename ...]

If no basename is given, the last deleted images in this session are restored.

positional arguments:
  • basenames: The basename(s) of the file in the trash directory.

version

Show a pop-up with version information.

syntax: :version [--copy]

optional arguments:
  • --copy: Copy version information to clipboard instead.

welcome-to-qt

Show a pop-up with a welcome message for users coming from gtk.

Image

Overview of image commands

Command

Description

center

Center the image in the viewport.

flip

Flip the image.

goto

Select specific image in current filelist.

metadata

Toggle display of exif metadata of current image.

metadata-list-keys

Display a list of all valid metadata keys for the current image.

play-or-pause

Toggle between play and pause of animation.

reload

Reload the current image.

rescale

Rescale the original image to a new size.

resize

Resize the original image to a new size.

rotate

Rotate the image.

scroll

Scroll the image in the given direction.

scroll-edge

Scroll the image to one edge.

slideshow

Toggle slideshow.

straighten

Display a grid to straighten the current image.

undo-transformations

Undo any transformation applied to the current image.

write

Save the current image to disk.

zoom

Zoom the current widget.

center

Center the image in the viewport.

flip

Flip the image.

syntax: :flip [--vertical]

optional arguments:
  • --vertical: Flip image vertically instead of horizontally.

goto

Select specific image in current filelist.

syntax: :goto index

positional arguments:
  • index: Number of the image to select.

Hint

-1 is the last image.

count: Select [count]th image instead.

metadata

Toggle display of exif metadata of current image.

count: Select the key set to display instead.

Hint

5 default key sets are provided and mapped to the counts 1-5. To override them or add your own, extend the METADATA section in your configfile like this:

keys2 = Override,Second,Set
keys4 = New,Fourth,Set

where the values must be a comma-separated list of valid metadata keys.

metadata-list-keys

Display a list of all valid metadata keys for the current image.

syntax: :metadata-list-keys [--n-cols=NUMBER] [--to-term]

optional arguments:
  • --n-cols: Number of columns used to display the keys.

  • --to-term: Print the keys to the terminal instead.

play-or-pause

Toggle between play and pause of animation.

reload

Reload the current image.

rescale

Rescale the original image to a new size.

syntax: :rescale dx [dy]

positional arguments:
  • dx: Factor in x direction to scale the image by.

  • dy: Factor in y direction to scale the image by. If not given, the aspectratio is preserved.

resize

Resize the original image to a new size.

syntax: :resize width [height]

positional arguments:
  • width: Width in pixels to resize the image to.

  • height: Height in pixels to resize the image to. If not given, the aspectratio is preserved.

rotate

Rotate the image.

syntax: :rotate [--counter-clockwise]

optional arguments:
  • --counter-clockwise: Rotate counter clockwise.

count: multiplier

scroll

Scroll the image in the given direction.

syntax: :scroll direction

positional arguments:
  • direction: The direction to scroll in (left/right/up/down).

count: multiplier

scroll-edge

Scroll the image to one edge.

syntax: :scroll-edge direction.

positional arguments:
  • direction: The direction to scroll in (left/right/up/down).

slideshow

Toggle slideshow.

count: Set slideshow delay to count instead.

straighten

Display a grid to straighten the current image.

The image can then be straightened clockwise using the l, > and L keys and counter-clockwise with h, < and H. Accept the changes with <return> and reject them with <escape>.

undo-transformations

Undo any transformation applied to the current image.

write

Save the current image to disk.

syntax: :write [path].

positional arguments:
  • path: Save to this path instead of the current one.

zoom

Zoom the current widget.

syntax: :zoom direction

positional arguments:
  • direction: The direction to zoom in (in/out).

count: multiplier

Library

Overview of library commands

Command

Description

goto

Select specific row in current filelist.

open-selected

Open the currently selected path.

scroll

Scroll the library in the given direction.

goto

Select specific row in current filelist.

syntax: :goto row

positional arguments:
  • row: Number of the row to select.

optional arguments:
  • --open-selected: Automatically open any selected image.

Hint

-1 is the last row.

count: Select [count]th element instead.

open-selected

Open the currently selected path.

If the path activated is an image, it is opened in image mode. If it is a directory, the library is loaded for this directory.

syntax: :open-selected [--close]

optional arguments:
  • --close: Close the library if an image was selected.

scroll

Scroll the library in the given direction.

syntax: :scroll direction

The behaviour is similar to the file manager ranger.

  • Scrolling right selects the current file.

  • Scrolling left selects the parent directory.

  • Scrolling up and down moves the cursor.

positional arguments:
  • direction: The direction to scroll in (left/right/up/down/page-up/page-down/half-page-up/half-page-down).

optional arguments:
  • --open-selected: Automatically open any selected image.

count: multiplier

Thumbnail

Overview of thumbnail commands

Command

Description

end-of-line

Select the last thumbnail in the current row.

first-of-line

Select the first thumbnail in the current row.

goto

Select specific thumbnail in current filelist.

open-selected

Open the currently selected thumbnail in image mode.

scroll

Scroll to another thumbnail in the given direction.

zoom

Zoom the current widget.

end-of-line

Select the last thumbnail in the current row.

first-of-line

Select the first thumbnail in the current row.

goto

Select specific thumbnail in current filelist.

syntax: :goto index

positional arguments:
  • index: Number of the thumbnail to select.

Hint

-1 is the last thumbnail.

count: Select [count]th thubnail instead.

open-selected

Open the currently selected thumbnail in image mode.

scroll

Scroll to another thumbnail in the given direction.

syntax: :scroll direction

positional arguments:
  • direction: The direction to scroll in (left/right/up/down/page-up/page-down/half-page-up/half-page-down).

count: multiplier

zoom

Zoom the current widget.

syntax: :zoom direction

positional arguments:
  • direction: The direction to zoom in (in/out).

count: multiplier

Command

Overview of command commands

Command

Description

complete

Invoke command line completion.

history

Cycle through command history.

history-substr-search

Cycle through command history with substring matching.

leave-commandline

Leave command mode.

nop

Do nothing.

complete

Invoke command line completion.

syntax: :complete [--inverse]

optional arguments:
  • --inverse: Complete in inverse direction.

history

Cycle through command history.

syntax: :history direction

positional arguments:
  • direction: The direction to cycle in (next/prev).

leave-commandline

Leave command mode.

nop

Do nothing.

This is useful to remove keys bound by Qt by explicitly binding them to nop.

Manipulate

Overview of manipulate commands

Command

Description

accept

Leave manipulate accepting the applied changes.

command

Enter command mode.

decrease

Decrease the value of the current manipulation.

discard

Discard any changes and leave manipulate.

fullscreen

Toggle fullscreen mode.

goto

Set the value of the current manipulation.

help

Show help on a command or setting.

history-clear

Clear the command history.

increase

Increase the value of the current manipulation.

keybindings

Show a pop-up with keybindings information.

next

Focus the next manipulation in the current tab.

next-tab

Focus the next manipulation tab.

nop

Do nothing.

prev

Focus the previous manipulation in the current tab.

prev-tab

Focus the previous manipulation tab.

set

Set an option.

accept

Leave manipulate accepting the applied changes.

command

Enter command mode.

syntax: :command [--text=TEXT]

optional arguments:
  • --text: String to append to the : prefix.

decrease

Decrease the value of the current manipulation.

syntax: :decrease value

positional arguments:
  • value: The value to decrease by.

count: multiplier

discard

Discard any changes and leave manipulate.

fullscreen

Toggle fullscreen mode.

goto

Set the value of the current manipulation.

syntax: :goto value

positional arguments:
  • value: Value to set the manipulation to.

count: Set the manipulation to [count] instead.

help

Show help on a command or setting.

syntax: :help topic

positional arguments:
  • topic: Either a valid :command or a valid setting name.

Hint

For commands help :command is the same as command -h.

history-clear

Clear the command history.

This clears the history of all modes unless --mode is passed.

syntax: :history-clear [--mode]

optional arguments:
  • --mode: Clear the history of the current mode only.

increase

Increase the value of the current manipulation.

syntax: :increase value

positional arguments:
  • value: The value to increase by.

count: multiplier

keybindings

Show a pop-up with keybindings information.

syntax: :keybindings [--columns=N]

optional arguments:
  • --columns: Number of columns to split the bindings in.

next

Focus the next manipulation in the current tab.

count: multiplier

next-tab

Focus the next manipulation tab.

count: multiplier

nop

Do nothing.

This is useful to remove keys bound by Qt by explicitly binding them to nop.

prev

Focus the previous manipulation in the current tab.

count: multiplier

prev-tab

Focus the previous manipulation tab.

count: multiplier

set

Set an option.

syntax: :set name [value]

positional arguments:
  • name: Name of the setting to set.

  • value: Value to set the setting to. If not given, set to default.