diff --git a/usync/04.command/01.getStarted/01.getCom.md b/usync/04.command/01.getStarted/01.getCom.md deleted file mode 100644 index e69de29..0000000 diff --git a/usync/04.command/01.getStarted/02.instCom.md b/usync/04.command/01.getStarted/02.instCom.md deleted file mode 100644 index e69de29..0000000 diff --git a/usync/04.command/01.getStarted/03.configCom.md b/usync/04.command/01.getStarted/03.configCom.md deleted file mode 100644 index e69de29..0000000 diff --git a/usync/04.command/01.getStarted/_category_.json b/usync/04.command/01.getStarted/_category_.json deleted file mode 100644 index 6259a3c..0000000 --- a/usync/04.command/01.getStarted/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Get Started", - "link": { - "type": "generated-index", - "title": "Get Started", - "description": "Get started with uSync.Commandline" - } -} \ No newline at end of file diff --git a/usync/04.command/01.index.md b/usync/04.command/01.index.md new file mode 100644 index 0000000..bcc02fa --- /dev/null +++ b/usync/04.command/01.index.md @@ -0,0 +1,21 @@ +--- +title: Welcome to uSync.CommandLine +--- + +# uSync.CommandLine for Umbraco v15+ + +v15 of the uSync.CommandLine utility uses the ManagementAPI (and the uSync Management API) to do the funky stuff without you having to install anything on the server. + +To install it, run this command: + +``` +dotnet tool install uSync.Cli --version 15.0.0-beta1 +``` + +To install this tool globally add -g to the command: + +``` +dotnet tool install -g uSync.Cli --version 15.0.0-beta1 +``` +Then it's time to [Create an API User](APIuser) + diff --git a/usync/04.command/02.commands/01.comBasics.md b/usync/04.command/02.commands/01.comBasics.md deleted file mode 100644 index 0e5730e..0000000 --- a/usync/04.command/02.commands/01.comBasics.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Command Basics ---- - -The uSync command has some things that are the same regardless of the commands you use. - -## Command line - -uSync commands all follow the same pattern. - -``` -uSync [command] [options] -``` - -Running `uSync -h` will give you a list of available commands. - -## Remote commands -Commands that connect to a remote server always need a way to authenticate with that server. - -At the moment there are two ways to authenticate a command: - -### Basic -Basic authentication uses an Umbraco username and password to connect to the remote server. - -``` -uSync [command] [options] -user -pass -``` - -The uSync commandline will use the supplied username and password to login to the Umbraco website. - -### HMAC -HMAC authentication uses a shared key to sign all communications between the command line and the site, this will be used to authorize the command on the Umbraco site. - -``` -uSync [command] [options] -key -``` - -The HMAC key needs to exist in the `appsettings.json` of the target site, and can be generated with the -`usync key-gen` command. \ No newline at end of file diff --git a/usync/04.command/02.commands/02.list.md b/usync/04.command/02.commands/02.list.md deleted file mode 100644 index 395744d..0000000 --- a/usync/04.command/02.commands/02.list.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: List ---- - -The List command lists all the available commands on a remote server. - -## Operation -The List command connects to a remote Umbraco installation and retrieves a list of commands that are avalible. - -## Options -*Remote connection options require a server address `-s` and ether a username `-user` and password `-pass` for basic auth or the Key `-key` if you are using HMAC auth.* - -Option | Note -|-|-| --s | URL of the server to connect to --user | Username to connect with --pass | Password of user --key | HMAC key to use for authentication - -## Example -``` -uSync list -s https://my-server.com/umbraco -user user@jumoo.co.uk -pass somepassword -``` - -Output -``` - *** uSync Command Line *** - -Remote commands available for https://my-server.com/umbraco : - - Info : Information about the Umbraco installation - Ping : Ping a server, returns true when server is ready - Rebuild-DbCache : Rebuilds the database cache (Expensive) - Rebuild-Index : Rebuilds an examine index - Reload-MemCache : Reloads the in-memory cache - Test : A test command, to check things work - uSync-Export : Run an uSync export - uSync-Import : Run an uSync import - uSync-Report : Run a uSync report - -For specific information on a single command : - > uSync list ... -To run a command : - > uSync run ... -``` - - -## Help - -``` -Description: - List server commands - -Usage: - uSync list [] [options] - -Arguments: - Command to get information about [] - -Options: - -s, --server (REQUIRED) Name or URL of server to connect to - -k, --key AuthKey to use when connecting to the server - -user, --username Username to use when logging into server - -pass, --password Password to use when logging into server - -?, -h, --help Show help and usage information -``` \ No newline at end of file diff --git a/usync/04.command/02.commands/03.run.md b/usync/04.command/02.commands/03.run.md deleted file mode 100644 index 03ec07f..0000000 --- a/usync/04.command/02.commands/03.run.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Run ---- - -# Operation -The Run command connects to the remote Umbraco instance and executes the given command. -It passes any parameters (supplied with the `-p` options) to the command. - -# Options -*Remote connection options require a server address `-s` and ether a username `-user` and password `-pass` for basic auth or the Key `-key` if you are using HMAC auth.* - -Option | Note -|-|-| -command | Name of the command to run --p | Parameters to add to the command --s | URL of the server to connect to --user | Username to connect with --pass | Password of user --key | HMAC key to use for authentication - -Parameters are passed either with multiple -p options or one -p option with spaces between the parameters. - -for example: - -``` --p option=value other=value2 -``` - -or -``` --p option=value -p other=value2 -``` - -# Example -``` -uSync run info -s https://my-server.com/umbraco -user user@jumoo.co.uk -pass somepassword -``` - -Output -``` - *** uSync Command Line *** - -{ - "version": "10.2.0", - "level": "Run", - "role": 1, - "servers": "https://localhost:44315/", - "environment": "Development", - "applicatioName": "UmbracoTenTwo", - "contentRootPath": "C:\\Source\\Testing\\Umbraco\\10\\UmbracoTenTwo" -} -``` - -# Help -``` - *** uSync Command Line *** - -Description: - Run a command against a server - -Usage: - uSync run [options] - -Arguments: - Command to issue to server - -Options: - -s, --server (REQUIRED) Name or URL of server to connect to - -p, --parameters Parameters to pass to server command - -k, --key AuthKey to use when connecting to the server - -user, --username Username to use when logging into server - -pass, --password Password to use when logging into server - -?, -h, --help Show help and usage information -``` \ No newline at end of file diff --git a/usync/04.command/02.commands/04.ping.md b/usync/04.command/02.commands/04.ping.md deleted file mode 100644 index b50d473..0000000 --- a/usync/04.command/02.commands/04.ping.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Ping ---- - -# Operation -The Ping command pings an Umbraco instance until it responds to the command (effectively the site is ready to accept more commands). - -# Options -|Option|Note -|-|-| --w | wait (timeout) between requests - -# Example -``` -uSync ping -s https://my-server.com/umbraco -user user@jumoo.co.uk -pass somepassword -``` - -Output -``` - *** uSync Command Line *** - -1...Timeout No connection could be made because the target machine actively refused it. (localhost:44315) -2...Timeout No connection could be made because the target machine actively refused it. (localhost:44315) -3...Timeout No connection could be made because the target machine actively refused it. (localhost:44315) -4...Successfully connected to https://localhost:44315/umbraco/ -``` - -# Help - -``` - *** uSync Command Line *** - -Description: - Ping a server until Umbraco is responding - -Usage: - uSync ping [options] - -Options: - -s, --server (REQUIRED) Name or URL of server to connect to - -w Timeout wait for each reply - -k, --key AuthKey to use when connecting to the server - -user, --username Username to use when logging into server - -pass, --password Password to use when logging into server - -?, -h, --help Show help and usage information -``` diff --git a/usync/04.command/02.commands/05.keyGen.md b/usync/04.command/02.commands/05.keyGen.md deleted file mode 100644 index 15af346..0000000 --- a/usync/04.command/02.commands/05.keyGen.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Key Gen ---- - -# Operation -Key Gen will generate a new HMAC key value that you can enter into your appsettings.json file if you want to use HMAC based authentication between your commandline and the Umbraco instance. - -``` -usync key-gen -``` - -Output -``` - *** uSync Command Line *** - -Key: iQi/kIMp5ggCc5DxOORVaA5kvuvaE8NRkB7uFxTRRLo= - -You will need to set this key in your servers appsetting.json file - -"uSync": { - "Commands": { - "Enabled": "hmac", - "key": "iQi/kIMp5ggCc5DxOORVaA5kvuvaE8NRkB7uFxTRRLo=" - } -} - -When running commands this value should make up the -key part of the command e.g - > uSync run info -s servername -k iQi/kIMp5ggCc5DxOORVaA5kvuvaE8NRkB7uFxTRRLo= -``` \ No newline at end of file diff --git a/usync/04.command/02.commands/_category_.json b/usync/04.command/02.commands/_category_.json deleted file mode 100644 index 644615c..0000000 --- a/usync/04.command/02.commands/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Commands", - "link": { - "type": "generated-index", - "title": "Commands", - "description": "Commands to run with uSync and how they work." - } -} \ No newline at end of file diff --git a/usync/04.command/03.coreRemote/01.info.md b/usync/04.command/03.coreRemote/01.info.md deleted file mode 100644 index 19e0ed6..0000000 --- a/usync/04.command/03.coreRemote/01.info.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Info ---- - -# Info -Returns information about the Umbraco installation. - -Usage : -``` -uSync run info -s https://my-server.com/umbraco -user user@jumoo.co.uk -pass somepassword -``` - -Output : -``` -{ - "version": "10.2.0", - "level": "Run", - "role": 1, - "servers": "https://localhost:44315/", - "environment": "Development", - "applicatioName": "UmbracoTenTwo", - "contentRootPath": "C:\\Source\\Testing\\Umbraco\\10\\UmbracoTenTwo" -} -``` - - diff --git a/usync/04.command/03.coreRemote/02.RebCache.md b/usync/04.command/03.coreRemote/02.RebCache.md deleted file mode 100644 index cf3ec6c..0000000 --- a/usync/04.command/03.coreRemote/02.RebCache.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Rebuild-DbCache ---- -Rebuild the Umbraco DbCache. - -Usage: -``` -uSync run rebuild-dbcache -s https://my-server.com/umbraco -user user@jumoo.co.uk -pass somepassword -``` - -Output: -``` - Database cache is ok. ContentStore contains 30 items and has 0 generation and 0 snapshot. MediaStore contains 23 items and has 0 generation and 0 snapshot. -``` \ No newline at end of file diff --git a/usync/04.command/03.coreRemote/03.rebIndex.md b/usync/04.command/03.coreRemote/03.rebIndex.md deleted file mode 100644 index 3c8755a..0000000 --- a/usync/04.command/03.coreRemote/03.rebIndex.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Rebuild-Index ---- -Rebuild an Examine index. - -``` -uSync run rebuild-Index -p index=ExternalIndex -s https://my-server.com/umbraco -user user@jumoo.co.uk -pass somepassword -``` \ No newline at end of file diff --git a/usync/04.command/03.coreRemote/04rebMem.md b/usync/04.command/03.coreRemote/04rebMem.md deleted file mode 100644 index 1c13500..0000000 --- a/usync/04.command/03.coreRemote/04rebMem.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Reload-MemCache ---- -Refreshes the memory cache. - -``` -uSync run Reload-MemCache -s https://my-server.com/umbraco -user user@jumoo.co.uk -pass somepassword -``` diff --git a/usync/04.command/03.coreRemote/05.test.md b/usync/04.command/03.coreRemote/05.test.md deleted file mode 100644 index e69de29..0000000 diff --git a/usync/04.command/03.coreRemote/_category_.json b/usync/04.command/03.coreRemote/_category_.json deleted file mode 100644 index ab3df51..0000000 --- a/usync/04.command/03.coreRemote/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Core Remote Commands", - "link": { - "type": "generated-index", - "title": "Core Remote Commands", - "description": " " - } -} \ No newline at end of file diff --git a/usync/04.command/04.usyncCommands/01.usyncImp.md b/usync/04.command/04.usyncCommands/01.usyncImp.md deleted file mode 100644 index e69de29..0000000 diff --git a/usync/04.command/04.usyncCommands/02.usyncEx.md b/usync/04.command/04.usyncCommands/02.usyncEx.md deleted file mode 100644 index e69de29..0000000 diff --git a/usync/04.command/04.usyncCommands/03.usyncRep.md b/usync/04.command/04.usyncCommands/03.usyncRep.md deleted file mode 100644 index e69de29..0000000 diff --git a/usync/04.command/04.usyncCommands/_category_.json b/usync/04.command/04.usyncCommands/_category_.json deleted file mode 100644 index b98f421..0000000 --- a/usync/04.command/04.usyncCommands/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "uSync.Commands", - "link": { - "type": "generated-index", - "title": "uSync.Commands", - "description": " " - } -} \ No newline at end of file diff --git a/usync/04.command/05.APIuser.md b/usync/04.command/05.APIuser.md new file mode 100644 index 0000000..df0f755 --- /dev/null +++ b/usync/04.command/05.APIuser.md @@ -0,0 +1,43 @@ +--- +title: Setting Up Umbraco for Commandline +--- + +In order to use uSync.CommandLine you have to make an API user. You can do this in the users section of Umbraco. + +![The create button in Users, showing the User and API User options in the dropdown.](add-api-user.png) + +Create the API user and add them to the relevant group! + +![Create API user tab in the users tab.](create-api-user.png) + +## Add a Client Secret and Key + +Once you have created an API user, you will need to give them a Client ID and Secret. + +![The client credentials tab.](client-secret.png) + +You will need both the Client ID and a Secret to connect via the CommandLine. + +![The create client credential window.](secret-id-tab.png) + +## Add an appsetting.json File + +You can add an appsettings.json file to the root of the folder where you are running uSync.CommandLine: + +``` +{ + "uSync": { + "Command": { + "Secret": "[CLIENT_SECRET]", + "ClientId": "[CLIENT_ID]" + } + } +} +``` +## Or Use the -k -i Settings + +Alternatively, you can pass these on the CommandLine. eg. + +`usynccli usync-ping -s https://localhost:44359 -s [client_secret] -k [client_id]` + +Once this is set up, you can use all the [Commands!](Commands) \ No newline at end of file diff --git a/usync/04.command/10.Commands.md b/usync/04.command/10.Commands.md new file mode 100644 index 0000000..6ee36c7 --- /dev/null +++ b/usync/04.command/10.Commands.md @@ -0,0 +1,47 @@ +--- +title: Available Commands +--- + +In this version we have plugged in the useful things you might need from the CommandLine. + +Rebuild indexes, models or caches, or run uSync imports or exports. + +```bash +uSync CommandLine: 15.0.0-beta1 + +Description: + +Usage: + `uSync [command] [options]` + +Options: + `--version Show version information` + `-?, -h, --help Show help and usage information` + ``` + +## What are the Commands? + +| Command | Description | +|--|--| + test | Test command + user-current | Fetch the user executing the commands + user-list | List all users + cache-rebuild | Rebuild the cache on the server + cache-reload | Reload the cache on the server + models-rebuild | Rebuild the models on the server + models-status | Get the status of the models on the server + indexer-rebuild | Rebuild the index on the server + indexer-list | List the indexes on the server + healthcheck-list | List the health checks on the server + healthcheck-group-list | List the health check groups on the server + healthcheck-group-check | Run a health check on the server + usync-settings | List all settings + usync-import | Import all items + usync-export | Export all items + usync-ping | Ping the Umbraco server until it responds + +e.g running an import: + +``` +uSyncCli usync-import -s https://myserver.com/ --force +``` diff --git a/usync/04.command/add-api-user.png b/usync/04.command/add-api-user.png new file mode 100644 index 0000000..85ed488 Binary files /dev/null and b/usync/04.command/add-api-user.png differ diff --git a/usync/04.command/client-secret.png b/usync/04.command/client-secret.png new file mode 100644 index 0000000..421c9c2 Binary files /dev/null and b/usync/04.command/client-secret.png differ diff --git a/usync/04.command/create-api-user.png b/usync/04.command/create-api-user.png new file mode 100644 index 0000000..e03ce39 Binary files /dev/null and b/usync/04.command/create-api-user.png differ diff --git a/usync/04.command/secret-id-tab.png b/usync/04.command/secret-id-tab.png new file mode 100644 index 0000000..213416f Binary files /dev/null and b/usync/04.command/secret-id-tab.png differ