Package: dccmd
DRACOON CommanderTable of ContentsAbout the ProjectBuilt WithGetting StartedPrerequisitesInstallationUsageConfigurationLicenseAbout the projectDisclaimer: This is an unofficial client and is not supported by DRACOON.This client is a CLI tool to perform basic commands in DRACOON and comes with the following functionalities:Full support for S3 direct up- / downloadChunked up- and downloadsFull support for DRACOON end-to-end encryptionOptimized for concurrent requestsStore credentials in OS-specific secure locationLinux: Freedesktop Secret Service (secretstorage)macOS: KeychainWindows: Windows Credential LockerBuilt WithtyperkeyringdracoonhttpxpoetryA full dependency list can be viewed inpyproject.toml- list of dependencies and project infopoetry.lockDRACOON Commander is built with typer as the CLI framework and uses keyring to store all credentials (OAuth2 tokens, client credentials and encryption password).
The tool is built on top of dracoon, an async API wrapper for DRACOON based on httpx.
The project is managed with poetry (dependencies, release build and publishing).Getting StartedIn order to get started, download the latest tarball from Github or install dccmd from pip:ReleasesPrerequisitesYou need a working Python 3.10 installation – dccmd makes use of type annotations and uses 3.10 features.
Get the latest Python version from:python.org.python3--versionIn order to get going, you can install dccmd either in a virtual environment or globally.InstallationTo install a version, usepipand install thedccmdpackage.In a virtual environmentvirtualenv<DIR>source<DIR>/bin/activatepython3-mpipinstalldccmdGloballypython3-mpipinstalldccmdSet PATHIn order for the script to work, you might need to add the relevant script path to your PATH.
When installing with pip, the output will already indicate if the path is present or not.
If you do not add the correct directory to PATH, you willnotbe able to use thedccmdcommand in your preferred shell.WindowsIn Windows, just add the script path by editing the environment variables for your account:
Look for an entry called 'Path' and install the script directory from thepip installoutput.UnixOn Linux or macOS you can add a path to PATH by using the following command:export PATH="/your/directory/see/install/output:$PATH"UsageDisplay commandsIn order to see all available commands, arguments and options, use the --help flag:dccmd--helpUsage: dccmd [OPTIONS] COMMAND [ARGS]...

Options:
  --install-completion [bash|zsh|fish|powershell|pwsh]
                                  Install completion for the specified shell.
  --show-completion [bash|zsh|fish|powershell|pwsh]
                                  Show completion for the specified shell, to
                                  copy it or customize the installation.
  --help                          Show this message and exit.

Commands:
  auth
  client
  crypto
  download  Download a file from DRACOON by providing a source path and a...
  ls        List all nodes in a DRACOON path
  mkdir     Create a folder in a DRACOON parent path
  mkroom    Create a room (inherit permissions) in a DRACOON parent path
  rm        Delete a file / folder / room in DRACOON
  upload    Upload a file into DRACOON by providing a source path and a...All commands display their own help message, e.g.dccmd upload --help.Client registration and authenticationBefore you can perform any command, you must authenticate and set up the client.
If you enter any command which requires authentication (e.g.dccmd ls your.dracoon.domain.com/), you will be prompted first for a client configuration:client idclient secretClientBefore you can usedccmdyou need to generate a client in your DRACOON instance (config manager role required).Create a client with a client id and client secret.
Please make sure you have the following settings active:Authorization codeRedirect URI is set tohttps://your.dracoon.domain.com/oauth/callbackOptional: If you wish to use the CLI mode (enter password and username via CLI), you can activate password flowCopy client id and client secret and use any command (e.g.dccmd ls your.dracoon.domain.com/).Enter client id and client secret – the information will be securely stored in your OS-specific secret container.AuthenticationOnce the client is set up, you will receive a link to authenticate via OAuth2 authorization code flow – you will then receive a code which you need to enter into the terminal.
When completed, you will be prompted to store credentials securely (OS-specific).Additionally, you can skip the authorization code flow and provide credentials directly, e.g. for thedccmd lscommand:dccmdlsyour-dracoon.domain.com/--cli-modeusername@mail.comtopsecret123!UploadImportant: if you use Windows, you need to provide the path with '/' instead of '\'!You can upload single files using the upload command:dccmdupload/path/to/file.pdfyour-dracoon.domain.com/In order to upload a directory, use the--recursive(-r) flag:dccmdupload-r/path/to/folderyour-dracoon.domain.com/Conflict resolutionIf you upload a file which already exists (based on file name), the upload will be rejected.In order to force an overwrite, use the--overwriteflag:dccmdupload/path/to/file.pdfyour-dracoon.domain.com/--overwriteIf you wish to auto-rename the file if it already exists, use theauto-renameflag:dccmdupload/path/to/file.pdfyour-dracoon.domain.com/--auto-renameAdvanced usageIf you upload folders recursively, you might encounter performance issues, specifically when uploading many small files.
You can therefore adjust concurrent file uploads via the--velocity(-v) flag:dccmdupload-r/path/to/folderyour-dracoon.domain.com/-v3The default value is 2 - it does not coincide with real request value.Maximum (although not recommended) value is 10. Entering higher numbers will result in max value use.Minimum value is 1 - this will not upload a folder per file but is the minimum concurrent request value. Entering lower numbers will result in min value use.If you need to understand why uploads fail, you can also run the command using the--debugflag:dccmdupload-r/path/to/folderyour-dracoon.domain.com/--debugNote: This will have impact on performance as the log will be streamed to terminal and the log level will be increased to DEBUG.Create folderIf you wish to create a folder, use themkdircommand:dccmdmkdiryour-dracoon.domain.com/parent/newfolderJust enter the full new path to create a folder.
You will needcreatepermission to do so.Create roomIf you wish to create a room, use themkroomcommand:dccmdmkroomyour-dracoon.domain.com/parent/newroomJust enter the full new path to create a room.
The room will be created as a room with inherited permissions from the parent.
You will needmanagepermission to do so.To create a room on the root level ('/'), you need to provide an admin user using
the corresponding option (-auor--admin-user):dccmdmkroom-au"admin.username"your-dracoon.domain.com/newroomNote: In order to use the username of an OIDC user, you need to escape the\, meaning you need to enter multiple slashes like so:OIDC\\\user.nameTo create a room on any level that doesnotinherit permissions, use the-au(--admin-user) flag and provide the room admin when creating the room as with root level rooms:dccmdmkroom-au"admin.username"your-dracoon.domain.com/parent-room/newroomDelete nodeIf you wish to delete a node, use thermcommand:dccmdrmyour-dracoon.domain.com/parent/somefile.pdfIn order to delete a container (room, folder) you need to use the--recursive(r) flag:dccmdrmyour-dracoon.domain.com/parent/folder/to/deleteWarning: Deleting rooms cannot be undone!List nodesIn order to list all nodes, use thelscommand:dccmdlsyour-dracoon.domain.com/Note: In order to list the root node, you need to provide a trailing/For a specific container (room or folder), use the path:dccmdlsyour-dracoon.domain.com/your/roomDisplaying additional informationUsing thelscommand by default only provides node names.
In order to display more information, use relevant flags:Display all information (size, last updated, last update user):--long(-l)Display sizes in human readable format (B, KB..):--human-readable(-h)Display node id:--inode(-i)Example displaying full information:dccmdls-h-i-lyour-dracoon.domain.com/your/roomDownloadTo download a file, use thedownloadcommand:dccmddownloadyour-dracoon.domain.com/your/cool-file.mp4/target/directoryTo download a room or a folder, use thedownloadcommand with--recursive(-r) flag:dccmddownload-ryour-dracoon.domain.com/your/cool-folder/target/directoryAdvanced usageIf you download folders recursively, you might encounter performance issues, specifically when downloading many small files.
You can therefore adjust concurrent file uploads via the--velocity(-v) flag:dccmdupload-r/path/to/folderyour-dracoon.domain.com/-v3The default value is 2 - it does not coincide with real request value.Maximum (although not recommended) value is 10. Entering higher numbers will result in max value use.Minimum value is 1 - this will not download a folder per file but is the minimum concurrent request value. Entering lower numbers will result in min value use.User operationsYou can list, edit and import users with relevantdccmd userscommand:csv-import  Add a list of users to DRACOON from a CSV filels          Get a list of users in DRACOONrm          Delete a userImporting usersYou can import users by using thecsv-importcommand and providing a path to the csv file:dccmduserscsv-import/path/to/users.csvyour-dracoon.domain.com/The csv file must contain a header and should include the following attributes:first namelast nameemaillogin (optional)By default, local users are created - if you want to import oidc users, you need pass the oidc config id:#example with OIDC config 5dccmduserscsv-import/path/to/users.csvyour-dracoon.domain.com/5Listing usersYou can list all users using thelscommand:dccmduserslsyour-dracoon.domain.com/You can get all users also as csv format by using the--csvflag:dccmduserslsyour-dracoon.domain.com/--csv>users.csvTo find a user, you can pass a search string to search for either first name, last name or user name (search string applies to all):# will return all users with either first name, last name or user name containing 'yourname'dccmduserslsyour-dracoon.domain.com/yournameDeleting usersYou can delete a user by providing the username:dccmdusersrmyour-dracoon.domain.com/user123Room permissions managementFor an overview of the available commands usedccmdrooms--helpList user / group permissions in a roomTo list user permissions in a room, use thelist-userscommand:dccmdroomslist-usersyour-dracoon.domain.com/your-roomYou need minimumreadpermissions to list users.To list group permissions in a room, use thelist-groupscommand:dccmdroomslist-groupsyour-dracoon.domain.com/your-roomYou need minimumreadpermissions to list groups.As with other commands, you can use the--csvflag to get a csv export for the room
permissions (users and groups).Add user / group to a roomCurrently, the following templates are available:read: read-only perrmissions for a roomedit: edit permissions for a roomadmin: room admin permissionsThe permissions coincide with the templates in use of the official DRACOON Web App.You needmanagepermissions (room admin) to add users / groups.To add a user, use theadd-usercommand and provide the user and permission template (-uand-p):dccmdroomsadd-user-u"user.name"-padminyour-dracoon.domain.com/your-roomTo add a group, use theadd-groupcommand and provide the group and permission template (-gand-p):dccmdroomsadd-group-g"group.name"-padminyour-dracoon.domain.com/your-roomRemove user / group from a roomYou needmanagepermissions (room admin) to remove users / groups.To add a user, use theremove-usercommand and provide the user (-u):dccmdroomsremove-user-u"user.name"your-dracoon.domain.com/your-roomTo add a group, use theremove-groupcommand and provide the group (-g):dccmdroomsremove-group-g"group.name"your-dracoon.domain.com/your-roomConfiguration / administrationYou can view / manage the configuration fordccmdusing the relevant commands:dccmd auth- manage credentialsdccmd auth ls your.dracoon.domain.comwill display if a refresh token has been stored for the provided domaindccmd auth rm your-dracoon.domain.comwill remove stored credentials for the provided domaindccmd client- manage clientdccmd client register your.dracoon.domain.comwill start the registration process for a client and given domaindccmd client ls your.dracoon.domain.comwill display client information for the provided domaindccmd client rm your-dracoon.domain.comwill remove the stored client config for the provided domaindccmd crypto- manage encryptiondccmd crypto ls your.dracoon.domain.comwill display if encryption password is stored for the provided domaindccmd crypto rm your-dracoon.domain.comwill remove the encryption password for the provided domaindccmd crypto distribute your-dracoon.domain.com/will generate file keys available to distribute - if providing a specific path (dccmd crypto distribute your-dracoon.domain.com/some/path), only keys for provided parent room will be generated.LoggingWhen using a command, a log will be created in the current working directory.
Currently it is not possible to configure a default path for a log.You can stream the log to stdout by using the--debugflag with any DRACOON-specific command (upload,download,ls,rm,mkdir,mkroom).LicenseDistributed under the Apache License. SeeLICENSEfor more information.