diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ac31fa5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,43 @@
+Spear provides possibility to display messages sent by [apocalypse](https://gitea.psi.ch/SwissFEL/apocalypse) (apo) when submitted job finishes.
+Content of the messages is displayed in form of a table by [stand](https://gitea.psi.ch/SwissFEL/stand).
+pgroup, run number, acquisition number and a timestamp of the message are added automatically by apo.
+Remaining columns are controlled by user by writing an apo meta file for each job.
+Meta file should be written to path mirroring raw path:
+
+`/sf/<endstation>/data/<pgroup>/res/processed/<run>/meta/apo_acq<acq>.[txt, json, yaml]`
+
+where:
+- `<endstation>` is the endstation running the experiment
+- `<pgroup>` is the pgroup of the experiment
+- `<run>` is the run folder name as given by daq
+- `<acq>` is acq number
+
+File can be written as plain txt, then whole content of the file will be treated as "message".
+When file is written as json or yaml file will be parsed and content of a dictionary key "table" will be parsed as columns.
+Each key in "table" dictionary needs to be a valid key argument for python, so while `"1"` will work, `1` will result in a crash.
+E.g. parsed content {"table":{"max":7, "min":1}, "operator":"noname"} will result in adding row:
+
+|pgroup|run_number|acq_number|t_stamp|max|min|
+|------|----------|----------|-------|---|---|
+|`<pgroup>`|`<run_number>`|`<acq_number>`|`<t_stamp>`|7|1|
+
+### Getting started
+#### Setup
+Run spear from virtual console:
+```bash
+ssh <endstation>-vcons-01
+```
+
+If you have `/sf/daq/bin` on your path, there is no need to do anything, otherwise:
+```bash
+export PATH=$PATH:/sf/daq/bin
+```
+
+#### Running
+```bash
+spear -e <endstation> -p <pgroup>
+```
+where:
+- `<endstation>` is the endstation that the corresponding data will be filtered for
+- `<pgroup>` is the pgroup that the corresponding data will be filtered for
+