docs/src/main/asciidoc/chapters/shell.txt

// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements.  See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License.  You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

== Accumulo Shell
Accumulo provides a simple shell that can be used to examine the contents and
configuration settings of tables, insert/update/delete values, and change
configuration settings.

The shell can be started by the following command:

  $ACCUMULO_HOME/bin/accumulo shell -u [username]

The shell will prompt for the corresponding password to the username specified
and then display the following prompt:

  Shell - Apache Accumulo Interactive Shell
  -
  - version 1.6
  - instance name: myinstance
  - instance id: 00000000-0000-0000-0000-000000000000
  -
  - type 'help' for a list of available commands
  -

=== Basic Administration

The Accumulo shell can be used to create and delete tables, as well as to configure
table and instance specific options.

----
root@myinstance> tables
accumulo.metadata
accumulo.root

root@myinstance> createtable mytable

root@myinstance mytable>

root@myinstance mytable> tables
accumulo.metadata
accumulo.root
mytable

root@myinstance mytable> createtable testtable

root@myinstance testtable>

root@myinstance testtable> deletetable testtable
deletetable { testtable } (yes|no)? yes
Table: [testtable] has been deleted.

root@myinstance>
----

The Shell can also be used to insert updates and scan tables. This is useful for
inspecting tables.

----
root@myinstance mytable> scan

root@myinstance mytable> insert row1 colf colq value1
insert successful

root@myinstance mytable> scan
row1 colf:colq [] value1
----

The value in brackets ``[]'' would be the visibility labels. Since none were used, this is empty for this row.
You can use the +-st+ option to scan to see the timestamp for the cell, too.

=== Table Maintenance

The *compact* command instructs Accumulo to schedule a compaction of the table during which
files are consolidated and deleted entries are removed.

  root@myinstance mytable> compact -t mytable
  07 16:13:53,201 [shell.Shell] INFO : Compaction of table mytable started for given range

The *flush* command instructs Accumulo to write all entries currently in memory for a given table
to disk.

  root@myinstance mytable> flush -t mytable
  07 16:14:19,351 [shell.Shell] INFO : Flush of table mytable
  initiated...

=== User Administration

The Shell can be used to add, remove, and grant privileges to users.

----
root@myinstance mytable> createuser bob
Enter new password for 'bob': *********
Please confirm new password for 'bob': *********

root@myinstance mytable> authenticate bob
Enter current password for 'bob': *********
Valid

root@myinstance mytable> grant System.CREATE_TABLE -s -u bob

root@myinstance mytable> user bob
Enter current password for 'bob': *********

bob@myinstance mytable> userpermissions
System permissions: System.CREATE_TABLE
Table permissions (accumulo.metadata): Table.READ
Table permissions (mytable): NONE

bob@myinstance mytable> createtable bobstable

bob@myinstance bobstable>

bob@myinstance bobstable> user root
Enter current password for 'root': *********

root@myinstance bobstable> revoke System.CREATE_TABLE -s -u bob
----

=== JSR-223 Support in the Shell

The script command can be used to invoke programs written in languages supported by installed JSR-223
engines. You can get a list of installed engines with the -l argument. Below is an example of the output
of the command when running the Shell with Java 7.

----
root@fake> script -l
    Engine Alias: ECMAScript
    Engine Alias: JavaScript
    Engine Alias: ecmascript
    Engine Alias: javascript
    Engine Alias: js
    Engine Alias: rhino
    Language: ECMAScript (1.8)
    Script Engine: Mozilla Rhino (1.7 release 3 PRERELEASE)
ScriptEngineFactory Info
----

 A list of compatible languages can be found at https://en.wikipedia.org/wiki/List_of_JVM_languages. The
rhino javascript engine is provided with the JVM. Typically putting a jar on the classpath is all that is
needed to install a new engine.

 When writing scripts to run in the shell, you will have a variable called connection already available
to you. This variable is a reference to an Accumulo Connector object, the same connection that the Shell
is using to communicate with the Accumulo servers. At this point you can use any of the public API methods
within your script. Reference the script command help to see all of the execution options. Script and script
invocation examples can be found in ACCUMULO-1399.