geode-docs/tools_modules/gfsh/getting_started_gfsh.html.md.erb - geode - Git at Google

 ---
 title:  Basic Shell Features and Command-Line Usage
 ---

 <!--
 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.
 -->

 The `gfsh` utility provides useful features for a shell environment, including command auto-complete, preserved command history, and delimiting of multi-line commands. Context-sensitive help is available by command and by topic.

 <a id="concept_45D28CC9710C4EAFB6EECFA0D651D439__section_A7A871DBD8C7464A80CEB007798E5AE7"></a>

 **To view a list of available gfsh commands, press Tab at an empty prompt.**

 The list of commands you see depends on whether you are connected to a <%=vars.product_name%> cluster. If you are not connected, you see a list of local commands that are available.

 **Use the hint command to get information on a particular topic.**

 The hint command displays a one-line description and associated commands for a specified topic. For example, **hint data** returns a description of the data topic and all the possible actions available for data:

 ``` pre
 gfsh>hint Data
 User data as stored in regions of the <%=vars.product_name%> distributed system.

 clear defined indexes: Clears all the defined indexes.
 create defined indexes: Creates all the defined indexes.
 create index: Create an index that can be used when executing queries.
 create lucene index: Create a lucene index that can be used to execute queries.
 define index: Define an index that can be used when executing queries.
 describe lucene index: Display the description of lucene indexes created for all members.
 destroy index: Destroy/Remove the specified index.
 destroy lucene index: Destroy the lucene index.
 export data: Export user data from a region to a file.
 get: Display an entry in a region. If using a region whose key and value classes have been set, then specifying --key-class and --value-class is unnecessary.
 import data: Import user data from a file to a region.
 list indexes: Display the list of indexes created for all members.
 list lucene indexes: Display the list of lucene indexes created for all members.
 locate entry: Identifies the location, including host, member and region, of entries that have the specified key.
 put: Add/Update an entry in a region. If using a region whose key and value classes have been set, then specifying --key-class and --value-class is unnecessary.
 rebalance: Rebalance partitioned regions. The default is for all partitioned regions to be rebalanced.
 remove: Remove an entry from a region. If using a region whose key class has been set, then specifying --key-class is unnecessary.
 search lucene: Search lucene index
 ```

 To view a list of hint topics, type `hint`.

 **Use the help command to get information on a particular command.**

 Depending on the command, typing `help <command-name>` displays usage information for that particular command or a list of commands related to the command.

 For example, type `help start` to display a list of start commands
 with short descriptions.
 The descriptions indicate whether the command is available,
 and depend on the connection status of `gfsh`.
 The following example assumes `gfsh` is not currently connected
 (via connection to a JMX Manager node),
 so some start commands are unavailable.

 ``` pre
 gfsh>help start
 start gateway-receiver (Not Available)
     Start the Gateway Receiver on a member or members.
 start gateway-sender (Not Available)
     Start the Gateway Sender on a member or members.
 start jconsole (Available)
     Start the JDK's JConsole tool in a separate process. JConsole will be
     launched, but connecting to GemFire must be done manually.
 start jvisualvm (Available)
     Start the JDK's Java VisualVM (jvisualvm) tool in a separate process. Java
     VisualVM will be launched, but connecting to GemFire must be done manually.
 start locator (Available)
     Start a Locator.
 start pulse (Available)
     Open a new window in the default Web browser with the URL for the Pulse
     application.
 start server (Available)
     Start a GemFire Cache Server.
 ```

 **Use the Tab key to auto-complete a command or trigger possible completions.**

 Use the Tab key after entering a partial command to trigger
 auto-completion of the command or a list of possible command completions.
 For example, hitting Tab after typing `hint` displays all available topics:

 ``` pre
 gfsh>hint

 Configuration           Data                    Debug-Utility
 Disk Store              Function Execution      GFSH
 GemFire                 Help                    JMX
 Lifecycle               Locator                 Management-Monitoring
 Manager                 Region                  Server
 Statistics
 ```

 Hitting tab after typing `hint d` displays the topics available that begin with 'd':

 ``` pre
 gfsh>hint d

 data            debug-Utility   disk Store
 ```

 Auto-completion also supplies available parameters and arguments to commands; for example, hitting tab after typing `start` will list all the processes that can be started.

 ``` pre
 gfsh>start

 start data-browser   start jconsole       start jvisualvm
 start locator        start pulse          start server
 ```

 Hitting tab after `start locator` will populate the `--name` parameter after the command.
 (If you do not specify a member name, gfsh will automatically pick a random name. This is useful for automation.)

 **Access command history with the Up arrow.**

 Access a command in your shell history by scrolling through previous commands with the Up arrow.

 **Delimit multi-line commands with a backslash.**

 When entering long commands, you can break the command line up
 by using the backslash character ('\\') as a delimiter. For example:

 ``` pre
 gfsh>create region --name=region1 \
 --type=REPLICATE_PERSISTENT \
 --cache-writer=org.apache.geode.examples.MyCacheWriter \
 --group=Group1 --disk-store=DiskStore1
 ```

 **Enclose strings that contain spaces or commas with single or double quotes**

 When you execute gfsh commands in the gfsh command shell,
 enclose any strings that contain spaces or commas in single quotes. For example:

 ``` pre
 gfsh>start locator --name='locator 1'
 ```

 ``` pre
 start locator --name=locator1 --port=9009 --mcast-port=0\
  --J='-Dgemfire.remote-locators=192.0.2.0[9009],192.0.2.1[9009]'
 ```

 When you execute multiple gfsh commands in a single line from the operating system shell, enclose the gfsh commands in double quotes. Within the double quotes, enclose any strings that contain spaces or commas with single quotes. For example:

 ``` pre
 $ gfsh -e "start locator --name='locator 1'" -e "start server --name=server1"
 ```
	---
	title: Basic Shell Features and Command-Line Usage
	---

	<!--
	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.
	-->

	The `gfsh` utility provides useful features for a shell environment, including command auto-complete, preserved command history, and delimiting of multi-line commands. Context-sensitive help is available by command and by topic.

	<a id="concept_45D28CC9710C4EAFB6EECFA0D651D439__section_A7A871DBD8C7464A80CEB007798E5AE7"></a>

	To view a list of available gfsh commands, press Tab at an empty prompt.

	The list of commands you see depends on whether you are connected to a <%=vars.product_name%> cluster. If you are not connected, you see a list of local commands that are available.

	Use the hint command to get information on a particular topic.

	The hint command displays a one-line description and associated commands for a specified topic. For example, hint data returns a description of the data topic and all the possible actions available for data:

	``` pre
	gfsh>hint Data
	User data as stored in regions of the <%=vars.product_name%> distributed system.

	clear defined indexes: Clears all the defined indexes.
	create defined indexes: Creates all the defined indexes.
	create index: Create an index that can be used when executing queries.
	create lucene index: Create a lucene index that can be used to execute queries.
	define index: Define an index that can be used when executing queries.
	describe lucene index: Display the description of lucene indexes created for all members.
	destroy index: Destroy/Remove the specified index.
	destroy lucene index: Destroy the lucene index.
	export data: Export user data from a region to a file.
	get: Display an entry in a region. If using a region whose key and value classes have been set, then specifying --key-class and --value-class is unnecessary.
	import data: Import user data from a file to a region.
	list indexes: Display the list of indexes created for all members.
	list lucene indexes: Display the list of lucene indexes created for all members.
	locate entry: Identifies the location, including host, member and region, of entries that have the specified key.
	put: Add/Update an entry in a region. If using a region whose key and value classes have been set, then specifying --key-class and --value-class is unnecessary.
	rebalance: Rebalance partitioned regions. The default is for all partitioned regions to be rebalanced.
	remove: Remove an entry from a region. If using a region whose key class has been set, then specifying --key-class is unnecessary.
	search lucene: Search lucene index
	```

	To view a list of hint topics, type `hint`.

	Use the help command to get information on a particular command.

	Depending on the command, typing `help <command-name>` displays usage information for that particular command or a list of commands related to the command.

	For example, type `help start` to display a list of start commands
	with short descriptions.
	The descriptions indicate whether the command is available,
	and depend on the connection status of `gfsh`.
	The following example assumes `gfsh` is not currently connected
	(via connection to a JMX Manager node),
	so some start commands are unavailable.

	``` pre
	gfsh>help start
	start gateway-receiver (Not Available)
	Start the Gateway Receiver on a member or members.
	start gateway-sender (Not Available)
	Start the Gateway Sender on a member or members.
	start jconsole (Available)
	Start the JDK's JConsole tool in a separate process. JConsole will be
	launched, but connecting to GemFire must be done manually.
	start jvisualvm (Available)
	Start the JDK's Java VisualVM (jvisualvm) tool in a separate process. Java
	VisualVM will be launched, but connecting to GemFire must be done manually.
	start locator (Available)
	Start a Locator.
	start pulse (Available)
	Open a new window in the default Web browser with the URL for the Pulse
	application.
	start server (Available)
	Start a GemFire Cache Server.
	```

	Use the Tab key to auto-complete a command or trigger possible completions.

	Use the Tab key after entering a partial command to trigger
	auto-completion of the command or a list of possible command completions.
	For example, hitting Tab after typing `hint` displays all available topics:

	``` pre
	gfsh>hint

	Configuration Data Debug-Utility
	Disk Store Function Execution GFSH
	GemFire Help JMX
	Lifecycle Locator Management-Monitoring
	Manager Region Server
	Statistics
	```

	Hitting tab after typing `hint d` displays the topics available that begin with 'd':

	``` pre
	gfsh>hint d

	data debug-Utility disk Store
	```

	Auto-completion also supplies available parameters and arguments to commands; for example, hitting tab after typing `start` will list all the processes that can be started.

	``` pre
	gfsh>start

	start data-browser start jconsole start jvisualvm
	start locator start pulse start server
	```

	Hitting tab after `start locator` will populate the `--name` parameter after the command.
	(If you do not specify a member name, gfsh will automatically pick a random name. This is useful for automation.)

	Access command history with the Up arrow.

	Access a command in your shell history by scrolling through previous commands with the Up arrow.

	Delimit multi-line commands with a backslash.

	When entering long commands, you can break the command line up
	by using the backslash character ('\\') as a delimiter. For example:

	``` pre
	gfsh>create region --name=region1 \
	--type=REPLICATE_PERSISTENT \
	--cache-writer=org.apache.geode.examples.MyCacheWriter \
	--group=Group1 --disk-store=DiskStore1
	```

	Enclose strings that contain spaces or commas with single or double quotes

	When you execute gfsh commands in the gfsh command shell,
	enclose any strings that contain spaces or commas in single quotes. For example:

	``` pre
	gfsh>start locator --name='locator 1'
	```

	``` pre
	start locator --name=locator1 --port=9009 --mcast-port=0\
	--J='-Dgemfire.remote-locators=192.0.2.0[9009],192.0.2.1[9009]'
	```

	When you execute multiple gfsh commands in a single line from the operating system shell, enclose the gfsh commands in double quotes. Within the double quotes, enclose any strings that contain spaces or commas with single quotes. For example:

	``` pre
	$ gfsh -e "start locator --name='locator 1'" -e "start server --name=server1"
	```