--- title: First steps description: Start the Amster OpenAM Shell client, explore available commands, and learn how to connect to an OpenAM instance component: pingam version: 8 page_id: pingam:amster:firststeps canonical_url: https://docs.pingidentity.com/pingam/8/amster/firststeps.html page_aliases: ["user-guide:amster-firststeps.adoc"] --- # First steps Once Amster is extracted, run the `amster` command to start the client: ``` $ cd /path/to/amster $ ./amster Amster OpenAM Shell (version build build, JVM: version) Type ':help' or ':h' for help ------------------------------------------------------------------------------ am> ``` The version of Amster is included in the first line of output, as well as the version of the running JDK. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------- | | | If the `amster` command fails to load, make sure the `JAVA_HOME` environment variable is set, and that your JDK version is supported. | To exit the client, run the `:exit` or `:q` commands: ``` am> :exit $ ``` To get a list of the commands available to the client, run the `:help` command: ``` am> :help For information about Groovy, visit: http://groovy-lang.org Available commands: connect (am ) Connect to an OpenAM instance create (c ) Create an OpenAM entity read (r ) Read an OpenAM entity update (u ) Update an OpenAM entity delete (d ) Delete an OpenAM entity query (q ) Query an OpenAM entity action (a ) Perform action an OpenAM entity import-config (i ) Import configuration into OpenAM export-config (x ) Export configuration from OpenAM replace (rep ) Replace all matching text install-openam (inst) Install OpenAM :help (:h ) Display this help message ? (:? ) Alias to: :help :exit (:x ) Exit the shell :quit (:q ) Alias to: :exit :load (:l ) Load a file or URL into the buffer . (:. ) Alias to: :load For help on a specific command type: :help command ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | To run an `update` command on an entity that contains a large number of key/value pairs, such as [DefaultAdvancedProperties](../entity-reference/sec-amster-entity-defaultadvancedproperties.html#sec-amster-entity-defaultadvancedproperties-global-ops-update), you must provide the entire JSON body, even if you only need to update a small subset of data.A simple way to do this is to run a `read` command, copy and edit the output, and paste it into the body of the `update` command. Alternatively, you can run `export-config`, copy the specific entity file to an identical empty file structure, edit the file, and call `import-config` setting the path to the top directory of the updated file structure. | To show help information available for a particular command, run `:help command`. For example: ``` am> :help connect usage: connect [options] Options: -i, --interactive If specified you will be prompted for credentials. Defaults to private key authentication. -k, --private-key Path to a private key file or directory containing one of amster_rsa, id_rsa or id_ecdsa. Defaults to {USER_HOME}/.ssh. -t, --connection-timeout The default timeout is 10 seconds. If specified, this parameter sets the timeout in seconds. Connect to the OpenAM instance at the given URL. Example: connect -i https://am.example.com/am connect -i -t 30 https://am.example.com/am ``` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When a command does not proceed as expected, it can sometimes be helpful to start the `amster` command in debug mode and try again. To activate debug mode, start the `amster` command using the `-d` flag. For example:``` $ ./amster -d Listening for transport dt_socket at address: 6006 DEBUG [org.codehaus.groovy.tools.shell.BufferManager] Created new buffer with index: 0 DEBUG [org.codehaus.groovy.tools.shell.BufferManager] Buffers reset DEBUG [org.codehaus.groovy.tools.shell.Parser] Using parser flavor: rigid …​ ```While in debug mode, the `amster` command output shows additional information, such as connection handshakes and Groovy calls. |