Synapse command line client¶
The Synapse Python Client can be used from the command line via the synapse command.
Installation¶
The command line client is installed along with installation of the Synapse Python client .
Usage¶
usage: synapse [-h] [--version] [-u SYNAPSEUSER] [-p SYNAPSEPASSWORD] [-c CONFIGPATH] [--debug] [-s]
{get,sync,store,add,mv,cp,associate,delete,query,submit,show,cat,list,set-provenance,get-provenance,set-annotations,get-annotations,create,store-table,onweb,login,test-encoding,get-sts-token}
...
Named Arguments¶
- --version
show program’s version number and exit
- -u, --username
Username used to connect to Synapse
- -p, --password
Password used to connect to Synapse
- -c, --configPath
Path to configuration file used to connect to Synapse [default: “/Users/jkiang/.synapseConfig”]
Default: “/Users/jkiang/.synapseConfig”
- --debug
Default: False
- -s, --skip-checks
suppress checking for version upgrade messages and endpoint redirection
Default: False
Sub-commands:¶
get¶
downloads a file from Synapse
synapse get [-h] [-q queryString] [-v VERSION] [-r] [--followLink] [--limitSearch projId] [--downloadLocation path] [--multiThreaded] [syn123]
Positional Arguments¶
- syn123
Synapse ID of form syn123 of desired data object.
Named Arguments¶
- -q, --query
Optional query parameter, will fetch all of the entities returned by a query (see query for help).
- -v, --version
Synapse version number of entity to retrieve. Defaults to most recent version.
- -r, --recursive
Fetches content in Synapse recursively contained in the parentId specified by id.
Default: False
- --followLink
Determines whether the link returns the target Entity.
Default: False
- --limitSearch
Synapse ID of a container such as project or folder to limit search for files if using a path.
- --downloadLocation
Directory to download file to [default: “./”].
Default: “./”
- --multiThreaded
Download file using a multiple threaded implementation. This flag will be removed in the future when multi-threaded download is deemed fully stable and becomes the default implementation.
Default: True
sync¶
Synchronize files described in a manifest to Synapse
synapse sync [-h] [--dryRun] [--sendMessages] [--retries INT] FILE
Positional Arguments¶
- FILE
A tsv file with file locations and metadata to be pushed to Synapse.
Named Arguments¶
- --dryRun
Perform validation without uploading.
Default: False
- --sendMessages
Send notifications via Synapse messaging (email) at specific intervals, on errors and on completion.
Default: False
- --retries
Default: 4
store¶
uploads and adds a file to Synapse
synapse store [-h] (--parentid syn123 | --id syn123 | --type TYPE) [--name NAME] [--description DESCRIPTION | --descriptionFile DESCRIPTION_FILE_PATH]
[--used [target [target ...]]] [--executed [target [target ...]]] [--limitSearch projId] [--noForceVersion] [--annotations ANNOTATIONS] [--replace]
[FILE]
Positional Arguments¶
- FILE
file to be added to synapse.
Named Arguments¶
- --parentid, --parentId, -parentid, -parentId
Synapse ID of project or folder where to upload data (must be specified if –id is not used.
- --id
Optional Id of entity in Synapse to be updated.
- --type
Type of object, such as “File”, “Folder”, or “Project”, to create in Synapse. Defaults to “File”
Default: “File”
- --name, -name
Name of data object in Synapse
- --description, -description
Description of data object in Synapse.
- --descriptionFile, -descriptionFile
Path to a markdown file containing description of project/folder
- --used, -used
Synapse ID, a url, or a local file path (of a file previouslyuploaded to Synapse) from which the specified entity is derived
- --executed, -executed
Synapse ID, a url, or a local file path (of a file previouslyuploaded to Synapse) that was executed to generate the specified entity
- --limitSearch
Synapse ID of a container such as project or folder to limit search for provenance files.
- --noForceVersion
Do not force a new version to be created if the contents of the file have not changed. The default is a new version is created.
Default: False
- --annotations
Annotations to add as a JSON formatted string, should evaluate to a dictionary (key/value pairs). Example: ‘{“foo”: 1, “bar”:”quux”}’
- --replace
Replace all existing annotations with the given annotations
Default: False
add¶
uploads and adds a file to Synapse
synapse add [-h] (--parentid syn123 | --id syn123 | --type TYPE) [--name NAME] [--description DESCRIPTION | --descriptionFile DESCRIPTION_FILE_PATH]
[--used [target [target ...]]] [--executed [target [target ...]]] [--limitSearch projId] [--noForceVersion] [--annotations ANNOTATIONS] [--replace]
[FILE]
Positional Arguments¶
- FILE
file to be added to synapse.
Named Arguments¶
- --parentid, --parentId, -parentid, -parentId
Synapse ID of project or folder where to upload data (must be specified if –id is not used.
- --id
Optional Id of entity in Synapse to be updated.
- --type
Type of object, such as “File”, “Folder”, or “Project”, to create in Synapse. Defaults to “File”
Default: “File”
- --name, -name
Name of data object in Synapse
- --description, -description
Description of data object in Synapse.
- --descriptionFile, -descriptionFile
Path to a markdown file containing description of project/folder
- --used, -used
Synapse ID, a url, or a local file path (of a file previouslyuploaded to Synapse) from which the specified entity is derived
- --executed, -executed
Synapse ID, a url, or a local file path (of a file previouslyuploaded to Synapse) that was executed to generate the specified entity
- --limitSearch
Synapse ID of a container such as project or folder to limit search for provenance files.
- --noForceVersion
Do not force a new version to be created if the contents of the file have not changed. The default is a new version is created.
Default: False
- --annotations
Annotations to add as a JSON formatted string, should evaluate to a dictionary (key/value pairs). Example: ‘{“foo”: 1, “bar”:”quux”}’
- --replace
Replace all existing annotations with the given annotations
Default: False
mv¶
Moves a file/folder in Synapse
synapse mv [-h] --id syn123 --parentid syn123
Named Arguments¶
- --id
Id of entity in Synapse to be moved.
- --parentid, --parentId, -parentid, -parentId
Synapse ID of project or folder where file/folder will be moved
cp¶
Copies specific versions of synapse content such as files, folders and projects by recursively copying all sub-content
synapse cp [-h] --destinationId syn123 [--version 1] [--setProvenance traceback] [--updateExisting] [--skipCopyAnnotations]
[--excludeTypes [file table [file table ...]]] [--skipCopyWiki]
syn123
Positional Arguments¶
- syn123
Id of entity in Synapse to be copied.
Named Arguments¶
- --destinationId
Synapse ID of project or folder where file will be copied to.
- --version, -v
Synapse version number of File or Link to retrieve. This parameter cannot be used when copying Projects or Folders. Defaults to most recent version.
- --setProvenance
Has three values to set the provenance of the copied entity-traceback: Sets to the source entityexisting: Sets to source entity’s original provenance (if it exists)None/none: No provenance is set
Default: “traceback”
- --updateExisting
Will update the file if there is already a file that is named the same in the destination
Default: False
- --skipCopyAnnotations
Do not copy the annotations
Default: False
- --excludeTypes
Accepts a list of entity types (file, table, link) which determines which entity types to not copy.
Default: []
- --skipCopyWiki
Do not copy the wiki pages
Default: False
associate¶
Associate local files with the files stored in Synapse so that calls to “synapse get” and “synapse show” don’t re-download the files but use the already existing file.
synapse associate [-h] [--limitSearch projId] [-r] path
Positional Arguments¶
- path
local file path
Named Arguments¶
- --limitSearch
Synapse ID of a container such as project or folder to limit search to.
- -r
Perform recursive association with all local files in a folder
Default: False
delete¶
removes a dataset from Synapse
synapse delete [-h] [--version VERSION] syn123
Positional Arguments¶
- syn123
Synapse ID of form syn123 of desired data object
Named Arguments¶
- --version
Version number to delete of given entity.
query¶
Performs SQL like queries on Synapse
synapse query [-h] [string [string ...]]
Positional Arguments¶
- string
A query string, see https://docs.synapse.org/rest/org/sagebionetworks/repo/web/controller/TableExamples.html for more information
submit¶
submit an entity or a file for evaluation
synapse submit [-h] [--evaluationID EVALUATIONID] [--evaluationName EVALUATIONNAME] [--entity ENTITY] [--file FILE] [--parentId PARENTID] [--name NAME]
[--teamName TEAMNAME] [--submitterAlias ALIAS] [--used [target [target ...]]] [--executed [target [target ...]]] [--limitSearch projId]
Named Arguments¶
- --evaluationID, --evaluationId, --evalID
Evaluation ID where the entity/file will be submitted
- --evaluationName, --evalN
Evaluation Name where the entity/file will be submitted
- --entity, --eid, --entityId, --id
Synapse ID of the entity to be submitted
- --file, -f
File to be submitted to the challenge
- --parentId, --parentid, --parent
Synapse ID of project or folder where to upload data
- --name
Name of the submission
- --teamName, --team
Submit of behalf of a registered team
- --submitterAlias, --alias
A nickname, possibly for display in leaderboards
- --used
Synapse ID, a url, or a local file path (of a file previouslyuploaded to Synapse) from which the specified entity is derived
- --executed
Synapse ID, a url, or a local file path (of a file previouslyuploaded to Synapse) that was executed to generate the specified entity
- --limitSearch
Synapse ID of a container such as project or folder to limit search for provenance files.
show¶
show metadata for an entity
synapse show [-h] [--limitSearch projId] syn123
Positional Arguments¶
- syn123
Synapse ID of form syn123 of desired synapse object
Named Arguments¶
- --limitSearch
Synapse ID of a container such as project or folder to limit search for provenance files.
cat¶
prints a dataset from Synapse
synapse cat [-h] [-v VERSION] syn123
Positional Arguments¶
- syn123
Synapse ID of form syn123 of desired data object
Named Arguments¶
- -v, --version
Synapse version number of entity to display. Defaults to most recent version.
list¶
List Synapse entities contained by the given Project or Folder. Note: May not be supported in future versions of the client.
synapse list [-h] [-r] [-l] [-m] syn123
Positional Arguments¶
- syn123
Synapse ID of a project or folder
Named Arguments¶
- -r, --recursive
recursively list contents of the subtree descending from the given Synapse ID
Default: False
- -l, --long
List synapse entities in long format
Default: False
- -m, --modified
List modified by and modified date
Default: False
set-provenance¶
create provenance records
synapse set-provenance [-h] -id syn123 [-name NAME] [-description DESCRIPTION] [-o [OUTPUT_FILE]] [-used [target [target ...]]] [-executed [target [target ...]]]
[-limitSearch projId]
Named Arguments¶
- -id, --id
Synapse ID of entity whose provenance we are accessing.
- -name, --name
Name of the activity that generated the entity
- -description, --description
Description of the activity that generated the entity
- -o, -output, --output
Output the provenance record in JSON format
- -used, --used
Synapse ID, a url, or a local file path (of a file previouslyuploaded to Synapse) from which the specified entity is derived
- -executed, --executed
Synapse ID, a url, or a local file path (of a file previouslyuploaded to Synapse) that was executed to generate the specified entity
- -limitSearch, --limitSearch
Synapse ID of a container such as project or folder to limit search for provenance files.
get-provenance¶
show provenance records
synapse get-provenance [-h] -id syn123 [--version version] [-o [OUTPUT_FILE]]
Named Arguments¶
- -id, --id
Synapse ID of entity whose provenance we are accessing.
- --version
version of Synapse entity whose provenance we are accessing.
- -o, -output, --output
Output the provenance record in JSON format
set-annotations¶
create annotations records
synapse set-annotations [-h] --id syn123 --annotations ANNOTATIONS [-r]
Named Arguments¶
- --id
Synapse ID of entity whose annotations we are accessing.
- --annotations
Annotations to add as a JSON formatted string, should evaluate to a dictionary (key/value pairs). Example: ‘{“foo”: 1, “bar”:”quux”}’
- -r, --replace
Replace all existing annotations with the given annotations
Default: False
get-annotations¶
show annotations records
synapse get-annotations [-h] --id syn123 [-o [OUTPUT_FILE]]
Named Arguments¶
- --id
Synapse ID of entity whose annotations we are accessing.
- -o, --output
Output the annotations record in JSON format
create¶
Creates folders or projects on Synapse
synapse create [-h] [-parentid syn123] -name NAME [-description DESCRIPTION | -descriptionFile DESCRIPTION_FILE_PATH] type
Positional Arguments¶
- type
Type of object to create in synapse one of {Project, Folder}
Named Arguments¶
- -parentid, -parentId, --parentid, --parentId
Synapse ID of project or folder where to place folder [not used with project]
- -name, --name
Name of folder/project.
- -description, --description
Description of project/folder
- -descriptionFile, --descriptionFile
Path to a markdown file containing description of project/folder
store-table¶
Creates a Synapse Table given a csv
synapse store-table [-h] --name NAME [--parentid syn123] [--csv foo.csv]
Named Arguments¶
- --name
Name of Table
- --parentid, --parentId
Synapse ID of project
- --csv
Path to csv
login¶
login to Synapse and (optionally) cache credentials
synapse login [-h] [-u SYNAPSEUSER] [-p SYNAPSEPASSWORD] [--rememberMe]
Named Arguments¶
- -u, --username
Username used to connect to Synapse
- -p, --password
Password or api key used to connect to Synapse
- --rememberMe, --remember-me
Cache credentials for automatic authentication on future interactions with Synapse
Default: False
get-sts-token¶
Get an STS token for access to AWS S3 storage underlying Synapse
synapse get-sts-token [-h] [-o {json,boto,shell,bash,cmd,powershell}] id {read_write,read_only}
Positional Arguments¶
- id
Synapse id
- permission
Possible choices: read_write, read_only
Named Arguments¶
- -o, --output
Possible choices: json, boto, shell, bash, cmd, powershell
Default: “shell”