Version 1.2 by Susan Evans on 2023/07/10 22:14
Hide last authors
Susan Evans 1.1 1 The Pilot Command Line Interface (pilotcli) is a binary executable program that provides a convenient way for users to perform file actions and platform-related tasks programmatically. The Pilot Command Line Interface can be downloaded and run on on your local Linux and Linux subsystems (as Windows user, see for instance the [[Windows Subsystem for Linux installation guide>>url:https://learn.microsoft.com/en-us/windows/wsl/install]]) to support large file uploads. For convenience, pilotcli is also pre-deployed and installed in the users JupyterHub accessible via worskpace tools.
2
3 = Data Stewardship =
4
5 Users are reminded to abide by the Platform Terms of Use and any Project-specific restrictions when using the Command Line Interface to access data and code.
6
7 = Using the Pilot Command Line Interface in JupyterHub =
8
9 To get started with the Pilot Command Line Interface in the HDC JupyterHub workspace tool, see the article //Using JupyterHub in HDC //and refer to the remaining sections in this article for a full description of the pilotcli commands.
10
11 = Downloading the Pilot Command Line Interface =
12
13 If you wish to use the Pilot Command Line Interface to upload large files from your local environment, it is necessary to download Pilot Command Line Interface tool on your Linux system. The recommended Linux version is Ubuntu 20.04.
14
15 * Download the pilotcli tool [[here>>url:https://object.hdc.humanbrainproject.eu/public-resources/pilotcli]].
16
17 After download, please grant execution permission to the binary file so that Pilot Command Line Interface can be used. To grant permission to the binary file, use the following command in the downloaded pilotcli directory.
18
19 {{code language="none"}}
20 $ chmod +x ./pilotcli
21 {{/code}}
22
23
24 If you have sudo permission, you can make the Pilot Command Line Interface more accessible in any directory by moving it to the /usr/local/bin directory:
25
26 {{code language="none"}}
27 $ mv ./pilotcli /usr/local/bin
28 {{/code}}
29
30 Without sudo permission, you can still use the Pilot Command Line Interface in a different directory by referring the Command Line Interface path. For example, use a command line Interface in the Downloads folder:
31
32 {{code language="none"}}
33 $ ~/Downloads/pilotcli
34 {{/code}}
35
36 = Pilot Command Line Interface Command Summary =
37
38 Commands are organized into main groups:
39
40 1. **User**// - //User related actions such as login and logout
41 1. **Project** //- //Project related actions, including list Project Names and Codes for all Projects accessible by the logged-in user.
42 1. **File **- Actions on files. User could use file action commands to list files/folders, upload files/folders, list/export attribute, and download files as well.
43 1. **Dataset **- Actions related to datasets.
44
45 = User Commands: pilotcli **user** =
46
47 == Help ==
48
49 {{code language="none"}}
50 $ pilotcli user --help
51 Usage: pilotcli user [OPTIONS] COMMAND [ARGS]...
52
53 Options:
54 --help Show this message and exit.
55
56 Commands:
57 login For user to login.
58 logout For user to logout.
59 {{/code}}
60
61 == Command: **login** ==
62
63 * **Options**: -u ~-~-username, -p ~-~-password
64 * **Usage**: Allows users to log into the platform through pilotcli. After login, the user must be actively using the Pilot Command Line Interface to remain logged in, or they will be logged out automatically after the session is idle for five minutes.
65 * **Prerequisites**: None.
66
67 {{code language="none"}}
68 $ pilotcli user login --help
69 Usage: pilotcli user login [OPTIONS]
70
71 For user to login.
72
73 Options:
74 --help Show this message and exit.
75 {{/code}}
76
77 === Example ===
78
79 User login:
80
81 1) Use the output device validation link or QR code to launch authentication validation:
82
83 {{code language="none"}}
84 $ pilotcli user login
85 Please, access https://iam.hdc.humanbrainproject.eu/realms/hdc/device?user_code=XXXX-XXXX to proceed
86 ▄▄▄▄▄▄▄ ▄▄ ▄ ▄ ▄ ▄▄▄▄ ▄ ▄▄▄▄▄▄▄
87 █ ▄▄▄ █ ▄ ▄▄▀█ █▀▀▀▄▀█▀ ▀██▄ █ ▄▄▄ █
88 █ ███ █ ██▄ ▀▀▄▀▄▄█▄ ▄ ▀▀▀▄ █ ███ █
89 █▄▄▄▄▄█ █▀▄▀█▀▄▀█▀▄ █ ▄ ▄ █▀█ █▄▄▄▄▄█
90 ▄▄▄▄▄▄▄ ▀█▀█▄▄█▄ █▀█ ▄▀▄▄ █ ▄ █▀▄▄▄
91 █ ▄▄▄ █ █▄█▄██ ▀ ▀█▀▀█ ▀▄█▄█▄▄▄█▀▄█
92 █ ███ █ █▀█ ▄▀██▄█▀▀█▄▀▀█▄▀█ ▀ ▀▄▀██
93 █▄▄▄▄▄█ ▄▀▄ ██▄▀▀▄ ▀▀▄ ▄▄▀▀▀▄ █▄▄▄█
94
95
96 Waiting validation finish...
97 {{/code}}
98
99 2) Grant access by clicking Yes:
100
101 [[image:Pilot CLI authentication.png||height="34%" width="40%"]]
102
103 3) Device Login Successful message will appear and your authentication browser window can be closed.
104
105 4) The output of the Command Line Tool will also be updated (see line 14 below) to notify you about the successful login:
106
107 {{code language="none"}}
108 $ pilotcli user login
109 Please, access https://iam.hdc.humanbrainproject.eu/realms/hdc/device?user_code=XXXX-XXXX to proceed
110 ▄▄▄▄▄▄▄ ▄▄ ▄ ▄ ▄ ▄▄▄▄ ▄ ▄▄▄▄▄▄▄
111 █ ▄▄▄ █ ▄ ▄▄▀█ █▀▀▀▄▀█▀ ▀██▄ █ ▄▄▄ █
112 █ ███ █ ██▄ ▀▀▄▀▄▄█▄ ▄ ▀▀▀▄ █ ███ █
113 █▄▄▄▄▄█ █▀▄▀█▀▄▀█▀▄ █ ▄ ▄ █▀█ █▄▄▄▄▄█
114 ▄▄▄▄▄▄▄ ▀█▀█▄▄█▄ █▀█ ▄▀▄▄ █ ▄ █▀▄▄▄
115 █ ▄▄▄ █ █▄█▄██ ▀ ▀█▀▀█ ▀▄█▄█▄▄▄█▀▄█
116 █ ███ █ █▀█ ▄▀██▄█▀▀█▄▀▀█▄▀█ ▀ ▀▄▀██
117 █▄▄▄▄▄█ ▄▀▄ ██▄▀▀▄ ▀▀▄ ▄▄▀▀▀▄ █▄▄▄█
118
119
120 Waiting validation finish...
121 Welcome to Command Line Tool!
122 {{/code}}
123
124 == Command: **logout** ==
125
126 * **Options**: -y ~-~-yes
127 * **Usage**: Allows users to log out of the platform through pilotcli.
128 * **Prerequisites**: User login is required, otherwise an error is returned: ‘The current login session is invalid. Please login to continue.'.
129
130 {{code language="none"}}
131 $ pilotcli user logout --help
132 Usage: pilotcli user logout [OPTIONS]
133
134 For user to logout.
135
136 Options:
137 -y, --yes Input Y/yes to confirm you want to logout, otherwise input N/no
138 to remain logged in.
139
140 --help Show this message and exit.
141 {{/code}}
142
143 === Examples ===
144
145 User logout:
146
147 {{code language="none"}}
148 $ pilotcli user logout
149 Are you sure you want to logout? [y/N]: y
150 Logged out successfully. Bye!
151 {{/code}}
152
153 User logout canceled:
154
155 {{code language="none"}}
156 $ pilotcli user logout
157 Are you sure you want to logout? [y/N]: n
158 Logout canceled!
159 {{/code}}
160
161 User logout with option to skip additional confirmation:
162
163 {{code language="none"}}
164 $ pilotcli user logout -y
165 Logged out successfully. Bye!
166 {{/code}}
167
168 = Project Commands: pilotcli **project** =
169
170 == Help ==
171
172 {{code language="none"}}
173 $ pilotcli project --help
174 Usage: pilotcli project [OPTIONS] COMMAND [ARGS]...
175
176 Options:
177 --help Show this message and exit.
178
179 Commands:
180 list List accessible projects.
181 {{/code}}
182
183 == Command: **list** ==
184
185 * **Options**: None
186 * **Usage**: List all Projects to which the user has access
187 * **Prerequisite**: User login is required, otherwise an error is returned: ‘The current login session is invalid. Please login to continue.'
188
189 {{code language="none"}}
190 $ pilotcli project list --help
191 Usage: pilotcli project list [OPTIONS]
192
193 List accessible projects.
194
195 Options:
196 --page INTEGER The page to be listed [default: 0]
197 --page-size INTEGER number of objects per page [default: 10]
198 --order [asc|desc] sorting order [default: desc]
199 --order-by [created_at|name|code]
200 sorting column [default: created_at]
201 -d, --detached whether run in detached mode
202 --help Show this message and exit.
203 {{/code}}
204
205 === Examples ===
206
207 Get a list of all Projects the user has access to:
208
209 {{code language="none"}}
210 $ pilotcli project list
211 Project Name Project Code
212 ---------------------------------------------------------------------------
213 Test Project 02-13 | test230213byshan
214 Test1_Audit | test1audit
215 Test20221109 | test20220109
216 Indoc Test Project | indoctestproject
217
218 Page: 0, Number of projects: 4
219 {{/code}}
220
221 By default, the table will only display the first ten elements. If the user has access to more than ten Projects, you will be prompted to use your arrow keys to select one of two options to either view the next ten items (//next page//), or to exit (//exit//). The selected option is indicated by two arrows and can be confirmed by hitting enter:
222
223 {{code language="none"}}
224 Page: 0, Number of projects: 10
225
226 What do you want? (Use arrow keys)
227 » next page
228 exit
229 {{/code}}
230
231 = File Commands: pilotcli **file** =
232
233 == Help ==
234
235 {{code language="none"}}
236 $ pilotcli file --help
237 Usage: pilotcli file [OPTIONS] COMMAND [ARGS]...
238
239 Options:
240 --help Show this message and exit.
241
242 Commands:
243 attribute-export Export attribute template from a given Project.
244 attribute-list List attribute templates of a given Project.
245 list List files and folders inside a given Project/folder.
246 resume Resume the upload process with given manifest file.
247 sync Download files/folders from a given Project/folder/file...
248 upload Upload files/folders to a given Project path.
249 {{/code}}
250
251 == Command: **attribute-list** ==
252
253 * **Options**: -p ~-~-project-code
254 * **Usage**: List all attributes from a specified Project.
Susan Evans 1.2 255 * **Prerequisite**:
Susan Evans 1.1 256
257 * User login is required, otherwise an error is returned: ‘The current login session is invalid. Please login to continue.’
Susan Evans 1.2 258 * Requires the Project code, which can be retrieved via {{code}}pilotcli project list{{/code}}.
Susan Evans 1.1 259
Susan Evans 1.2 260 {{code language="none"}}
261 $ pilotcli file attribute-list --help
262 Usage: pilotcli file attribute-list [OPTIONS]
Susan Evans 1.1 263
Susan Evans 1.2 264 List attribute templates of a given Project.
Susan Evans 1.1 265
Susan Evans 1.2 266 Options:
267 -p, --project-code TEXT Project Code
268 --help Show this message and exit.
269 {{/code}}
Susan Evans 1.1 270
Susan Evans 1.2 271
272
273
274
Susan Evans 1.1 275 ----
276
277 -
278 {{code language="none"}}{{/code}}
279
280 ----
281
282 Copyright © 2023 [[Indoc Research>>url:https://www.indocresearch.org/]].
283
Susan Evans 1.2 284 HealthDataCloud is powered by Pilot technology, a product of [[Indoc Research>>url:https://www.indocresearch.org/]].~{~{/code}}
285 ~)~)~)