Introduction
EasyMorph Server Command Line Client (in further text – ems-cmd) allows you to run server commands via REST API.
Requirements
Compatible OS:
OS Windows x86/x64 with .Net 4.7.2 or later
OS Windows/ Linux / MacOS with dotnet 3.1 or higher (netcoreapp3.1)
EasyMorh Server
Morph.Server.Sdk.dll (deployed together with ems-cmd). Also hosted on github
EasyMorph Server 1.2 or higher (installed on a separate machine)
Download
ems-cmd comes together with EasyMorph Server. Also it can be downloaded separately
General command format:
ems-cmd <commad> <host> -param1 value1 -param2 "value two"
where
<command>
- command to execute. See Commands section for details.<host>
- Server host likehttp://192.168.100.200:6330
.
exit codes
ems-cmd may return one of the following exit codes:
0
ems-cmd was successfully run to completion.1
A fatal error occurred during command parsing or execution.
Authorization
For password protected spaces you should pass password via command parameter -password
.
ems-cmd upload http://192.168.100.200:6330 -space Default -password your_password -source D:\your\local\folder\file.xml -target \
In the example above, a session will be opened for the specified space Default, of course if password was correct. In case of incorrect password or public spaces, error will be thrown. Some hash computations are applied to the password before it is sent to the server.
Commands
Status and metadata
Retrieve server status
ems-cmd status http://192.168.100.200:6330
Parameters
This command has no additional parameters
Output
Retrieving server status...
STATUS:
StatusCode: OK
StatusMessage: Server is OK
ServerVersion:1.3.0.0
List spaces
A list of all spaces will be displayed. This command doesn't require authorization.
ems-cmd listspaces http://192.168.100.200:6330
Parameters
This command has no additional parameters
Output
Available spaces:
* closed one
Default
Listing done
Asterisk *
means that the space requires an authorization.
Space status
Returns specified space status. This command may require authorization if space is password protected.
ems-cmd spacestatus http://192.168.100.200:6330 -space "closed one" -password some_password
Parameters
-space
- space name.-password
- if password is required.
Output
Checking space default status...
Space: Default
IsPublic: True
Permissions: FilesList, FileDownload
done
Tasks
List tasks
This command will list all tasks in the space.
ems-cmd listtasks http://192.168.100.200:6330 -space Default
Parameters
-space
- space name, e.g.Default
Output
Listing tasks in the space default
0c73012f-0704-44a2-a3f5-ae54df3edd05: wait
235cc252-2eb2-4b6c-b6b4-7b92eabf5494: f
f69efa25-b649-47d5-a5ff-3772358a8aec: wait
Listing done
Get task metadata
Allows obtaining metadata about a task and its settings.
ems-cmd gettask http://192.168.100.200:6330 -space Default -taskID 59b824f0-4b81-453f-b9e0-1c58b97c9fb9
Parameters
-space
- space name, e.g.Default
-taskID
- task guid.
Output
Attempting to get task 59b824f0-4b81-453f-b9e0-1c58b97c9fb9 in space 'default'
Info about task:
Id:'59b824f0-4b81-453f-b9e0-1c58b97c9fb9'
Name:'f'
IsRunning:'False'
Enabled:'True'
Note:''
ProjectPath:'C:\Users\Public\Documents\Morphs\f.morph'
StatusText:'Idle'
TaskState:'Idle'
Task Parameters:
Parameter 'ZText' = 'some text' [Text] (Note: ZText annotation)
Parameter 'ZDate' = '2000-01-15' [Date] (Note: ZDate annotation)
Parameter 'ZFile' = 'C:\Users\Public\Documents\Morphs\file.csv'
[FilePath] (Note: ZFile annotation)
Done
Start a task synchronously
This command will start the specified task and wait until it is finished.
To start the task you need to know the space name and the task ID. See the task execution server log to determine task execution info.
ems-cmd run http://192.168.100.200:6330 -space Default -taskID 59b824f0-4b81-453f-b9e0-1c58b97c9fb9
Parameters
-space
- space name, e.g.Default
-taskID
- task guid.-param:XXX ZZ
- set task parameterXXX
with valueZZ
.
Task guid can be found in the browser location toolbar. E.g, if you have clicked on the edit task link, your browser location seems to be http://localhost:6330/default/tasks/edit/59b824f0-4b81-453f-b9e0-1c58b97c9fb9
, where 59b824f0-4b81-453f-b9e0-1c58b97c9fb9
- is a desired value
If you want to pass (or override) parameters that were defined in morph project, add -param:XXX ZZ
to ems-cmd execution line.
Where XXX
is a parameter name and ZZ
is a parameter value.
At least one space between parameter name and parameter value is required.
E.g. If you've defined parameter Timeout
in your morph project, and want to set it to 73 use -param:Timeout 73
. Pay attention, that parameters are case sensitive.
Examples:
Set parameter Rounds
to 10
: -param:Timeout 73
Set parameter Full name
to John Smith
: -param:"Full name" "John Smith"
Set parameter From Date
to the 10th of December 2000
: -param:"From Date" "2000-12-10"
(ISO 8601 date format)
Output
Attempting to start task 59b824f0-4b81-453f-b9e0-1c58b97c9fb9
Project 'sample.morph' is running. Waiting until done.
Task 59b824f0-4b81-453f-b9e0-1c58b97c9fb9 completed
Start a task asynchronously (fire and forget)
This command return control immediately after task was enqueued
To start the task you need to know task space name and task ID. Make sure to check the task execution log at server to determine task execution status.
ems-cmd runasync http://192.168.100.200:6330 -space Default -taskID 59b824f0-4b81-453f-b9e0-1c58b97c9fb9
Parameters
-space
- space name, e.g.Default
-taskID
- task guid.-param:XXX ZZ
- set task parameterXXX
with valueZZ
.
Task guid can be found in the browser location toolbar. E.g, if you have clicked on the edit task link, your browser location seems to be http://localhost:6330/default/tasks/edit/59b824f0-4b81-453f-b9e0-1c58b97c9fb9
, where 59b824f0-4b81-453f-b9e0-1c58b97c9fb9
- is a desired value
If you want to pass (or override) parameters that were defined in morph project, add -param:XXX ZZ
to ems-cmd execution line.
Where XXX
is a parameter name and ZZ
is a parameter value.
At least one space between parameter name and parameter value is required.
E.g. If you've defined parameter Timeout
in your morph project, and want to set it to 73 use -param:Timeout 73
. Pay attention, that parameters are case sensitive.
Examples:
Set parameter Rounds
to 10
: -param:Timeout 73
Set parameter Full name
to John Smith
: -param:"Full name" "John Smith"
Set parameter From Date
to the 10th of December 2000
: -param:"From Date" "2000-12-10"
(ISO 8601 date format)
Output
Attempting to start task 59b824f0-4b81-453f-b9e0-1c58b97c9fb9
Project 'sample.morph' is running.
Files
Browse files
This command shows the contents of a folder.
ems-cmd browse http://192.168.100.200:6330 -space Default -location "\folder 2"
Parameters
-space
- space name, e.g.Default
-location
- remote folder(relative path in the space-space
).
Output
Browsing the folder 'folder 2' of the space Default
Space: Default
Free space: 7820345344 bytes
09/05/2017 09:39:22 PM <DIR> Folder 2.1
09/20/2017 09:45:33 AM <DIR> Folder 3
09/28/2017 03:44:16 PM 8,123 project.morph
Listing done
Download a file
This command will download one single file from server.
If local file already exists, you will be prompted to overwrite it.
Notice, that when you are using a redirected output (e.g. to the file) and local file already exists, download will fail.
In any case, you may use parameter /y
to overwrite existing file without any prompts.
Be careful with folders that contain spaces in their names. You should add quotation marks around such parameter values.
Keep in mind, that sequence \"
will escape double quotes. So don't use it at the end of the parameter value.
ems-cmd download http://192.168.100.200:6330 -space Default -target D:\your\local\folder -source file.xml
ems-cmd download http://192.168.100.200:6330 -space Default -target D:\your\local\folder -source \file.xml
ems-cmd download http://192.168.100.200:6330 -space Default -target D:\your\local\folder -source \server\folder\file.xml
ems-cmd download http://192.168.100.200:6330 -space Default -target "D:\local\folder with spaces" -source "server\folder with spaces\file3.xml"
Parameters
-space
- space name, e.g.Default
-target
- destination folder (you local folder).-source
- relative path to file in the space-space
/y
- overwrite existing file (silent agree)
Output
Downloading file 'server\folder\file.xml' from space 'Default' into 'D:\your\local\folder'...
Operation completed
Upload a file
This command will upload one single to Server.
If remote file already exists, you will be prompted to overwrite it.
Notice, that when you are using a redirected output (e.g. to the file) and remote file already exists, upload will fail.
In any case, you may use parameter /y
to overwrite existing file without any prompts.
Be careful with folders that contain spaces in their names. You should add quotation marks around such parameter values.
Keep in mind, that sequence \"
will escape double quotes. So don't use it at the end of the parameter value.
ems-cmd upload http://192.168.100.200:6330 -space Default -source D:\your\local\folder\file.xml -target \
ems-cmd upload http://192.168.100.200:6330 -space Default -source D:\your\local\folder\file2.xml -target "folder 2"
ems-cmd upload http://192.168.100.200:6330 -space Default -source D:\your\local\folder\file2.xml -target "folder 2\sub folder"
ems-cmd upload http://192.168.100.200:6330 -space Default -source "D:\local\folder with spaces" -target "folder 2\sub folder"
Parameters
-space
- space name, e.g.Default
-target
- destination folder (remote folder, relative path in the space-space
).-source
- path to your local file/y
- overwrite existing file (silent agree)
Output
Uploading file 'D:\your\local\folder\file.xml' to folder '\' of space 'Default'...
Operation completed
Delete file
This command will delete a remote file.
ems-cmd del http://192.168.100.200:6330 -space Default -target "folder 2\file.xml"
Parameters
-space
- space name, e.g.Default
-target
- relative path in the space-space
to file
SSL errors
In case if you want to suppress ssl errors, use additional parameter /suppress-ssl-errors
.
ems-cmd del http://192.168.100.200:6330 -space Default -target "folder 2\file.xml" /suppress-ssl-errors
License
ems-cmd is licensed under the MIT license.