From cfb9a5f688e6347408cee46ce04dd1ed7851107d Mon Sep 17 00:00:00 2001 From: jjg-123 Date: Sun, 3 Nov 2024 05:08:12 -0600 Subject: [PATCH] Update the CLI help. --- .../src/site/xhtml/server/manuals/cli.xhtml | 220 ++++++++++-------- 1 file changed, 118 insertions(+), 102 deletions(-) diff --git a/website/src/site/xhtml/server/manuals/cli.xhtml b/website/src/site/xhtml/server/manuals/cli.xhtml index 91e037a3e..43d0089e1 100644 --- a/website/src/site/xhtml/server/manuals/cli.xhtml +++ b/website/src/site/xhtml/server/manuals/cli.xhtml @@ -5,8 +5,6 @@ Command line tools - - -

Command line tools for OA4MP

These are a set of programs that are accessible from a CLI @@ -84,98 +81,42 @@ records and approvals. There is also the option to copy a store completely from store to another.

Getting the tools

- -

The latest version of the Oauth 2.0 command line tool is available at -oa2-cli.jar -You should also get the script that runs this too, -oa2-cli +

+ Generally you should use the installer + and follow the instructions for that. This will deploy and configure a fully functional + CLI for your server. If you really insist on downloading and running the jar manually, + please the Appendix.

-

Configuration

-The tool uses a standard configuration file exactly like the server. Indeed, you can just + +

Configuration

+

The tool uses a standard configuration file exactly like the server. Indeed, you can +(and generally should) just point the tool at the server configuration file. You will need to supply the name of -the configuration in the file you want to use. Aliases can be quite handy here. Given the abilities of +the configuration in the file you want to use. Configuration file aliases (these are internal +to the can be quite handy here. Given the abilities of the CLI to do quick copies of the store, it pays to have a backup (file) store configured and occasionally simple copy the active store to that. There are many possible uses. It is assumed that -the tools are installed in a location called $OA4MP_HOME. Normally the default for this is +the tools are installed in a location called $OA4MP_SERVER. Normally the default for this is

-OAuth 1.0a: OA4MP_HOME=/opt/oa4mp -

-OAuth 2.0: OA4MP_HOME=opt/oa2 - -Note that we will be discussing the OA4MP tools rather than the OA2 tools in what follows. - Everything here works the same if you replace oa4mp-* by oa2-* +OA4MP_SERVER=/opt/oa4mp/server +

The assumption of the script is that files are in the following directory structure

-The default name of the configuration is assumed to be "default" (no quotes). If you invoke the script with -no arguments it will use this and the above configuration file. - -

Running the CLI

-Invocation from the command line is usually done with the supplied shell script, oa4mp-cli. The -invocation syntax is
- -
oa4mp-cli [configName configFile]
- -You should run this as root and might need to set the script to be -executable if it is not. If you give neither arguments then defaults are used. Invoke with the argument "--help" -for more information. If you give one argument it is assumed to be the configuration name -in the default configuration file. -

Command line options for the jar.

-You should run this from the script, but if you want or need to specify -invoke the jar directly, the invocation options they are listed here. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ArgumentValue required?Required?Description
-cfgYYThe full path to the configuration file.
-nameFFThe name of the configuration within the file. If there is a single configuration - in the file, then no name is needed. If there are multiple configurations you must specify which one to use.
-logFFThe full path log file. If this is not specified then a file named "log.xml" - is dumped into the invocation directory.
-useFFSpecify the component to use. Rather than loading the whole CLI then use-ing - a components (such as clients) you may simply specify that here.
-vFFNo argument. Turns on verbose logging so that much more information is dumped - onto the console. This is useful for debugging or just if you want to see what it is up to.
-
-    java -jar oa4mp-cli.jar -cfg /path/to/cfg.xml -name myConfig -log /path/to/mylog.xml -use approvals
-
-This would load the configuration named "myConfig" from the given file, write the log to a file called -"mylog.xml" and bring up the approvals component. +

The default name of the configuration is assumed to be "default" (no quotes). If you invoke the script with + no arguments it will use this and the above configuration file. Invocation syntax is

+ +
java -jar $OA4MP_SERVER/lib/cli.jar  [configName configFile env]
+
    +
  1. configName = name of the configuration in the file
    2. +
  2. configFile = full path to the configuration file
    3. +
  3. env = full path to a properties fiel that has environment variables set in it. + (This is specialized and can usually be omitted.)
    4. +
+

Note that you may shorten the list, but cannot, e.g., just supply the configuration file.

Help!

For every command you may add the switch --help and you will get @@ -227,14 +168,16 @@ view the help for the ls command:

Meta commands

-

There are commands to do tasks and there are meta-commands that control how the +

The OA4MP CLI extends the NCSA CLI framework, + so meta commands are more fully discussed there. + There are commands to do tasks and there are meta-commands that control how the CLI itself operates. These are prefixed with a backslash /. E.g. to quit a component, issue

/q

A full listing of meta commands is done with the ?:

/?
-

Extremely use meta-commands are a command history, executing a command in another component -with out switching from the current one, saving you command history (useful if you want +

Commonly used meta-commands are a command history, executing a command in another component +without switching from the current one, saving you command history (useful if you want to use a set of commands as a basis for some scripting). To list the commands available for the admin component, you would issue

@@ -264,7 +207,7 @@ will just change to that component and exiting it will return to you the origina
 The CLI consists of utilities for each component that can be used. Once invoked you will see
 the startup banner and prompt:
 
-[mybox bin]# ./oa4mp-cli
+[mybox bin]# ./cli
 **********************************************************
 * OA4MP CLI (Command Line Interpreter)                   *
 * Version 6.0                                          *
@@ -274,11 +217,11 @@ the startup banner and prompt:
 * type 'help' for a list of commands                     *
 *      'exit' or 'quit' to end this session.             *
 **********************************************************
-oa2>
+oa4mp>
 

 If you type "--help" You will get
 
-oa2>--help
+oa4mp>--help
 
 Here are the commands available:
 use
@@ -296,7 +239,7 @@ Basic supported commands are
 
 To see the help for, say, the use command you would issue
 
-   oa2>use --help
+   oa4mp>use --help
     Choose the component you wish to use.
     you specify the component as use + name. Supported components are
     clients - edit client records
@@ -351,8 +294,8 @@ operations with the 

 
command. Related is the get_id to display the current id and the clear_id
 to clear it. If you have an default id set, you do not need to specify one.

 
-    oa2>set_id foo:bar/34456
-    oa2>ls -l
+    oa4mp>set_id foo:bar/34456
+    oa4mp>ls -l
   name : My test thing
     id : foo:bar/34456
 

@@ -382,12 +325,12 @@ This will print the number of elements in the current storage component. 

 Example. For showing the number of clients in a store
 you would have something like the following
 
-oa2>use clients
+oa4mp>use clients
   clients >size
     Current store has 22 entries
   clients >exit
 exiting ...
-oa2>
+oa4mp>
 

 
 
Listing Object or Details of an Object.

@@ -644,7 +587,7 @@ deserialization commands against it repeatedly as you debug it.

 
 
Clients

 Invoke as
-
oa2> use clients

+
oa4mp> use clients

 Operations allowed in addition to the standard ones are
 
    
     
  • 
@@ -673,14 +616,14 @@ clients>
 
 
    Approvals
    
 Invoke as
-
    oa2> use approvals
    
+
    oa4mp> use approvals
    
  There are no extra options beyond the standard ones, however, the create command
 takes the unique id of the client record you are going to approve. Once created, you may enter the
 approval information directly.
 
 
    Copy
    
 Invoke as
-
    oa2>use copy
    
+
    oa4mp>use copy
    
 Supported operation is
 
      
     
    • cp source target [-verify] - copy source to target optionally verifying
      • 
@@ -691,7 +634,80 @@ that the every object in the target is deleted, so no merge takes place. If the
 then the two stores are compared once the copy has been completed. Note that this can be very time consuming
 for a large store! However, if there is any question it is at times very useful.
 
+
      Appendix
      
+
      Getting and installing it manually
      
+
      You can just download the jar and configure it manually, though that is a lot more
+    work than the installer. One cogent argument is incorporating the CLI into your own custome scripts.
+    This section is how to run the CLI fromthe jara manually. If you use the installer,
+    skip this section.
      
+
      The latest version of the OA4MP command line tool is available at
+    cli.jar
+    You should also get the script that runs this too,
+    cli
+
      
+
      If you are pointing to the server configuration, you will probably need to run this as root
+    to get access top that file.  If you invoke the CLI with no arguments, it will tell
+    you there is no configuration, but you can use all of the online help.
+    You need the configuration file and name of the configuration generally to get a working
+    CLI.
      
+
+
      Running the CLI jar
      
+
      invocation syntax is just like any other executable jar
      
+
+
      java -jar $OA4MP_SERVER/lib/cli.jar  options
      
+
+
      Command line options for the jar.
      
+You should run this from the script, but if you want or need to specify
+invoke the jar directly, the invocation options they are listed here.
+
+    
+    
+        
+        
+        
+        
+    
+    
+        
+        
+        
+        
+    
+    
+        
+        
+        
+        
+    
+    
+        
+        
+        
+        
+    
+    
+        
+        
+        
+        
+    
+    
+        
+        
+        
+        
+    
+    
+
      ArgumentValue required?Required?Description
      -cfgYYThe full path to the configuration file.
      -nameFFThe name of the configuration within the file. If there is a single configuration
+            in the file, then no name is needed. If there are multiple configurations you must specify which one to use. 
      -logFFThe full path log file. If this is not specified then a file named "log.xml"
+            is dumped into the invocation directory.
      -useFFSpecify the component to use. Rather than loading the whole CLI then use-ing
+            a components (such as clients) you may simply specify that here.
      -vFFNo argument. Turns on verbose logging so that much more information is dumped
+            onto the console. This is useful for debugging or just if you want to see what it is up to.
      
+
      +    java -jar cli.jar -cfg /path/to/cfg.xml -name myConfig -log /path/to/mylog.xml -use approvals
+
      
+This would load the configuration named "myConfig" from the given file, write the log to a file called
+"mylog.xml" and bring up the approvals component.
 
-
 
 
\ No newline at end of file