From 8916d32df35f1174e49f2161fe7a846b80c70635 Mon Sep 17 00:00:00 2001
From: Romin <15949-romin.benfer@users.noreply.git.rwth-aachen.de>
Date: Tue, 22 Apr 2025 17:39:19 +0200
Subject: [PATCH] Add documentation for coscine executable

---
 .gitignore         |  4 +--
 docs/executable.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.md      |  1 +
 3 files changed, 71 insertions(+), 2 deletions(-)
 create mode 100644 docs/executable.md

diff --git a/.gitignore b/.gitignore
index 436b360..2ba1201 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,8 +2,8 @@
 *
 
 # Except
-!docs/*
-!docs/_static/*
+!docs/
+!docs/**
 !src
 !src/coscine
 !src/coscine/*.py
diff --git a/docs/executable.md b/docs/executable.md
new file mode 100644
index 0000000..22ae07d
--- /dev/null
+++ b/docs/executable.md
@@ -0,0 +1,68 @@
+# Executable
+### Working from the command-line
+Since version `0.11.11`, the Coscine Python SDK provides
+a command-line executable program written in Python.
+This makes it easier to interact with Coscine for basic actions
+such as:
+
+* Delete: Delete a project, resource or file.
+* Download: Download a project, resource or file.
+* List: List projects, resources or files.
+* Upload: Upload a file to a resource.
+
+without the need to write an extra python script.
+
+### Usage
+After installing the Coscine Python SDK on your system you can run
+the Coscine executable with the following command:
+```bash
+py -m coscine
+```
+or simply `coscine` if you have python modules on path (e.g. in a venv).
+
+You need to specify a Coscine API token to use the executable, either
+via a command-line argument:
+```bash
+coscine -t "My Coscine API Token"
+```
+
+or via an environment variable:
+```bash
+export COSCINE_API_TOKEN="My Coscine API Token" # on Linux
+set COSCINE_API_TOKEN=MyCoscineAPIToken # on Windows
+```
+
+### Actions
+The following snippets assume that the Coscine API Token has been set
+as an environment variable.
+
+#### Delete Action
+
+```bash
+coscine delete -p "My Coscine Project" # deletes the project
+coscine delete -p "My Coscine Project" -r "My Coscine Resource" # deletes the resource
+coscine delete -p "My Coscine Project" -r "My Coscine Resource" -f "My file path" # deletes the file
+```
+
+#### Download Action
+
+```bash
+coscine download -p "My Coscine Project" # downloads the project
+coscine download -p "My Coscine Project" -r "My Coscine Resource" # downloads the resource
+coscine download -p "My Coscine Project" -r "My Coscine Resource" -f "My file path" # downloads the file
+```
+
+#### List Action
+
+```bash
+coscine list # lists all projects
+coscine list -p "My Coscine Project" # lists all resources inside the project
+coscine list -p "My Coscine Project" -r "My Coscine Resource" # lists all files inside the resource
+```
+
+#### Upload Action
+
+```bash
+# Uploads a file to the resource
+coscine upload -p "My Coscine Project" -r "My Coscine Resource" -f "Local file path"
+```
diff --git a/docs/index.md b/docs/index.md
index 542e961..cb5f5e9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -48,6 +48,7 @@ project
 resource
 metadata
 publish
+executable
 API Reference<genindex>
 modindex
 build
-- 
GitLab