mongovi.1

.\" Copyright (c) 2016 Tim Kuijsten
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: November 15 2016 $
.Dt MONGOVI 1
.Os
.Sh NAME
.Nm mongovi
.Nd command line interface for MongoDB
.Sh SYNOPSIS
.Nm
.Op Fl psV
.Op Ar path
.Nm
.Fl i
.Ar path
.Sh DESCRIPTION
.Nm
is a cli for MongoDB that uses
.Xr editline 3
for line editing and key bindings.
It can be used both interactively and non-interactively i.e. via shell scripts.
.Bl -tag -width Ds
.It Fl p
Print output in a human readable format.
This is the default when stdout is connected to a terminal.
Mutually exclusive with
.Fl s .
.It Fl s
Print each JSON document on a single line in canonical MongoDB Extended JSON
format.
This is the default when stdout is not connected to a terminal.
Mutually exclusive with
.Fl p .
.It Fl i
Import mode.
Read MongoDB Extended JSON documents from stdin and insert them into the
database.
Each line must contain one document and not any
.Nm
commands.
.It Fl V
Print version information and exit.
.It Ar path
Open a specific database or collection.
See
.Sx PATH ARGUMENT
for more info.
.El
.Pp
The default key bindings are Emacs-like.
.Xr vi 1 Ns -like
key bindings can be enabled by putting
.Qq bind -v
into the
.Xr editrc 5
file.
.Pp
By default
.Nm
will connect to mongodb://localhost:27017 unless it is overridden with a
connection string in
.Pa ~/.mongovi .
.Ss BUILTIN COMMANDS
The following commands are supported:
.Bl -tag -width Ds
.It Ic find Op Ar selector
List all documents in the currently selected collection.
If connected to a terminal then documents are output in a human readable format
(which can be overridden with
.Fl s No ).
If not connected to a terminal then documents are output in canonical MongoDB
Extended JSON format (which can be overridden with
.Fl p No ).
.It Ic count Op Ar selector
Count all documents in the currently selected collection.
.It Ic remove Ar selector
Remove all documents in the currently selected collection that match the
selector.
.It Ic update Ar selector Ar doc
Update all documents that match the selector using the provided update document.
.It Ic upsert Ar selector Ar doc
Update or insert a document that matches the selector using the provided
document.
.It Ic insert Ar doc
Insert
.Ar doc
into the currently selected collection.
.Ar doc
is parsed as MongoDB Extended JSON.
.It Ic aggregate Op Ar pipeline
Run an aggregation query using the given pipeline.
.It Ic cd Op Ar path
Change the currently selected database or collection to
.Ar path .
If
.Ar path
is a single dash
.Pq Sq -
the previous path will be selected.
If
.Ar path
is absent the first path since
.Nm
started is selected.
See
.Sx PATH ARGUMENT
for more info.
.It Ic cd Ar old new
The string
.Ar new
is substituted for
.Ar old
in the currently selected path.
.It Ic ls Op Ar path ...
List the contents of each
.Ar path .
If path is absent the currently selected path is used.
.It Ic drop Op Ar path ...
Drop the collection or database described by each
.Ar path .
In case path is absent the currently selected path is dropped.
.It Ic help
Print the list of commands.
.It Ic exit
Alias for
.Sm off
.Sq No ^ Ar D .
.Sm on
Quits
.Nm .
.El
.Pp
Any command can be abbreviated to the shortest non-ambiguous form.
So
.Ar find
can also be written as
.Ar f
since no other command starts with an f.
.Pp
If selector is not a JSON document it is treated as a shortcut to search on _id
of type string.
Hexadecimal strings of 24 characters are treated as object ids.
.Ss PATH ARGUMENT
Several commands take a
.Ar path
parameter.
A path can be seen as a file hierarchy in which the root contains one directory
per database and where each database contains one directory per collection.
A path without a leading
.Qq /
is treated as a path relative to the currently selected database or collection.
A path that starts with a
.Qq /
is considered an absolute path.
A
.Qq ..
component can be used to traverse up in the hierarchy.
.Sh FILES
.Pa ~/.mongovi
If it exists the first line is read and used as a MongoDB connection string.
This string can contain a username and password.
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
List all databases non-interactively:
.Bd -literal -offset 4n
$ echo ls | mongovi
.Ed
.Pp
Open database
.Qq foo
and collection
.Qq bar :
.Bd -literal -offset 4n
$ mongovi /foo/bar
/foo/bar>
.Ed
.Pp
Change the currently selected collection to
.Qq sabar :
.Bd -literal -offset 4n
/foo/bar> cd ../sabar
/foo/sabar>
.Ed
.Pp
List documents where
.Qq foo
is
.Qq bar :
.Bd -literal -offset 4n
/foo/bar> f { foo: "bar" }
.Ed
.Pp
Quick search on Object ID:
.Bd -literal -offset 4n
/foo/bar> f 57c6fb00495b576b10996f64
.Ed
.Pp
Use an aggregation query to filter on documents where
.Qq foo
is
.Qq bar .
Note that
.Ar aggregate
is abbreviated to
.Ar a :
.Bd -literal -offset 4n
/foo/bar> a [{ $project: { foo: true } }, { $match: { foo: "bar" } }]
.Ed
.Pp
Copy one collection to another:
.Bd -literal -offset 4n
$ echo f | mongovi /foo/bar | mongovi -i /qux/baz
.Ed
.Sh SEE ALSO
.Xr editrc 5 ,
.Xr editline 7
.Pp
.Lk https://www.mongodb.com/docs/manual/reference/connection-string/ "Connection String URI Format" ,
.Lk https://www.mongodb.com/docs/manual/reference/mongodb-extended-json/ "MongoDB Extended JSON (v2)"
.Sh AUTHORS
.An -nosplit
.An Tim Kuijsten