English | 简体中文

Python client for ETAPI of Trilium Note.

• 🐍 trilium-py
  • 🦮 Table of Contents
  • 🔧 Installation
  • 📖 (Basic) Usage
    • 🚀 Initialization
    • 📊 Application Information
    • 🔍 Search note
    • 🏭 Create Note
      • 🖼️ Create Image note
    • 👀 Get note
    • 🔄 Update note
    • 🗑️ Delete note
    • 📅 Day note
    • 📤 Export note
    • 💾 Create data backup
    • 🏷 Create attribute
    • Get attachment info
    • Update attachment info
    • Get attachment content
    • Update attachment content
    • Create attachment
  • (Advanced Usage) ✅ TODO List
    • Add TODO item
    • Check/Uncheck a TODO item
    • Update a TODO item
    • Delete a TODO item
    • Move yesterday's unfinished todo to today
  • (Advanced Usage) 🚚 Upload Markdown files
    • Upload single Markdown file with images
    • Bulk upload Markdown files in a folder
      • Import from VNote
      • Import from Joplin
      • Import from Logseq
      • Import from Obsidian
      • Import from Youdao Note/有道云笔记
      • Import from Turtl
      • Import from other markdown software
  • (Advanced Usage) 🎨 Beautify notes
    • Beautify a note
    • Beautify a note and its child notes
  • (Advanced Usage) 🧹 Sort note content
  • (Advanced Usage) 🧹 Delete empty new note
  • 🛠️ Develop
  • 🔗 Original OpenAPI Documentation

python3 -m pip install trilium-py --user

These are basic function that Trilium's ETAPI provides. Down below are some simple example code to use this package.

If you have a ETAPI token, change the server_url and token to yours.

from trilium_py.client import ETAPI

server_url = 'http://localhost:8080'
token = 'YOUR_TOKEN'
ea = ETAPI(server_url, token)

If you haven't created ETAPI token, you can create one with your password. Please note, you can only see this token once, please save it if you want to reuse the token.

from trilium_py.client import ETAPI

server_url = 'http://localhost:8080'
password = '1234'
ea = ETAPI(server_url)
token = ea.login(password)
print(token)

After initialization, you can use Trilium ETAPI with python now. The following are some examples.

To start with, you can get the application information like this.

print(ea.app_info())

It should give you the version of your server application and some extra information.

Search note with keyword.

res = ea.search_note(
    search="python",
)

for x in res['results']:
    print(x['noteId'], x['title'])

Search with regular expression. For example, search and get all child notes under certain note:

res = ea.search_note(
    # regular expression search for note title
    search="note.title %= '.*'",
    ancestorNoteId="Parent Note ID",
    fastSearch=False,
    limit=1000,
)

You can create a simple note like this.

res = ea.create_note(
    parentNoteId="root",
    title="Simple note 1",
    type="text",
    content="Simple note example",
    noteId="note1"
)

The noteId is not mandatory, if not provided, Trilium will generate a random one. You can retrieve it in the return.

noteId = res['note']['noteId']

Image note is a special kind of note. You can create an image note with minimal information like this. The image_file refers to the path of image.

res = ea.create_image_note(
    parentNoteId="root",
    title="Image note 1",
    image_file="shield.png",
)

To retrieve the note's content.

ea.get_note_content("noteid")

You can get a note metadata by its id.

ea.get_note(note_id)

Update note content

ea.update_note_content("noteid", "updated by python")

Modify note title

ea.patch_note(
    noteId="noteid",
    title="Python client moded",
)

Simply delete a note by id.

ea.delete_note("noteid")

You can get the content of a certain date with get_day_note. The date string should be in format of "%Y-%m-%d", e.g. " 2022-02-25".

ea.get_day_note("2022-02-25")

Then set/update a day note with set_day_note. The content should be a (html) string.

ea.set_day_note(date, new_content)

Export note comes in two formats html or markdown/md.

res = ea.export_note(
    noteId='sK5fn4T6yZRI',
    format='md',
    savePath='/home/nate/data/1/test.zip',
)

This example will create a database backup file like this trilium-data/backup/backup-test.db.

res = ea.backup("test")

You can use the cron utility in Linux to schedule regular automatic backups. For example, to set up a daily backup at 3: 00 AM, you would use the following cron expression:

0 3 * * * python /path/to/backup-script.py

You can create a tag for a note

res = ea.create_attribute(
    noteId='noteid',
    type='label',
    name='name_of_the_tag',
    value='value_of_the_tag',
    isInheritable=True
)

The noteId is not mandatory, if not provided, Trilium will generate a random one. You can retrieve it in the return.

noteId = res['note']['noteId']

Get image title and etc.

res = ea.get_attachment('Y5V6pYq6nwXo')

Change image title and etc.

res = ea.update_attachment(
    attachmentId='2b7pPzqocS1s', title='hello etapi', role='image', mime='image/png'
)

Get the real image file

res = ea.get_attachment_content('icpDE4orQxlI')
with open('1.png', 'wb') as f:
    f.write(res)

Replace the image with new one

res = ea.update_attachment_content('icWqV6zFtE0V', '/home/nate/data/1.png')

Upload a image file as attachment of a note.

res = ea.create_attachment(
    ownerId='8m8luXym5LxT',
    file_path='/home/nate/data/ksnip_20230630-103509.png',
)

With the power of Python, I have expanded the basic usage of ETAPI. You can do something with todo list now.

You can use add_todo to add a TODO item, param is the TODO description

ea.add_todo("买暖宝宝")

param is the index of the TODO item

ea.todo_check(0)
ea.todo_uncheck(1)

Use update_todo to update a TODO item description at certain index.

ea.update_todo(0, "去码头整点薯条")

Remove a TODO item by its index.

ea.delete_todo(1)

As the title suggests, you can move yesterday's unfinished things to today. Unfinished todo's will be deleted from yesterday's note.

ea.move_yesterday_unfinished_todo_to_today()

You can import Markdown file with images into Trilium now! Trilium-py will help you to upload the images and fix the links for you!

res = ea.upload_md_file(
    parentNoteId="root",
    file="./md-demo/manjaro 修改caps lock.md",
)

You can upload a folder with lots of Markdown files to Trilium and preserve the folder structure!

Say, upload all the notes from VNote, simply do this:

res = ea.upload_md_folder(
    parentNoteId="root",
    mdFolder="~/data/vnotebook/",
    ignoreFolder=['vx_notebook', 'vx_recycle_bin', 'vx_images', '_v_images'],
)

Joplin can be imported effortlessly.

res = ea.upload_md_folder(
    parentNoteId="root",
    mdFolder="/home/nate/data/joplin_data/",
    ignoreFolder=['_resources', ],
)

res = ea.upload_md_folder(
    parentNoteId="root",
    mdFolder="/home/nate/data/logseq_data/",
    ignoreFolder=['assets', 'logseq'],
)

Obsidian has a very unique linking system for files. You should use obsidian-export to convert a Obsidian vault to regular Markdown files. Then you should be able to import the note into Trilium with trilium-py.

Convert it first.

obsidian-export /path/to/your/vault /out

Then import just like a normal markdown, trilium-py will handle the images for you.

res = ea.upload_md_folder(
    parentNoteId="root",
    mdFolder="E:/data/out",
)

Youdao does not provide an export feature anymore. Luckily, you can use https://github.com/DeppWang/youdaonote-pull to download your notes and convert them into markdown files. After that, trilium-py should be able to help you import them.

res = ea.upload_md_folder(
    parentNoteId="root",
    mdFolder="/home/nate/gitRepo/youdaonote-pull/out/",
)

You need to convert Turtl from json to markdown first. See turtl-to-markdown for details.

Then you can import with trilium-py like this:

res = ea.upload_md_folder(
    parentNoteId="root",
    mdFolder="/home/nate/gitRepo/turtl-to-markdown/out/",
    ignoreFolder=['_resources'],
)

In general, markdown files have variety of standards. You can always try import them with

res = ea.upload_md_folder(
    parentNoteId="root",
    mdFolder="/home/nate/data/your_markdown_files/",
)

If there is any problem, please feel free to create an issue.

Because of the constraints imposed by the library utilized by Trilium, imported notes may experience minor formatting problems. These issues include an additional line appearing at the end of code blocks, images becoming integrated with the note content, and the absence of line breaks between headings, resulting in a cramped appearance of the note content.

Here is what you can do to beautify your note.

Specify a note id to beautify note content.

ea.beautify_note('krm8B9JthNfi')

ea.beautify_sub_notes('tlPuzU2szLJh')

Sort a note by the heading names. This feature could prove invaluable for notes containing extensive lists, such as book titles sorted into various genres. It's equally useful for managing browser bookmarks or collecting links.

Additionally, you have the option to specify a language code for sorting based on your local language. This enhances the sorting process and tailors it to your linguistic preferences.

res = ea.sort_note_content('lPxtkknjR2bJ')
res = ea.sort_note_content('y6hROhWjNmHQ', 'zh_CN.UTF-8')

Sometimes I inadvertently create numerous "new notes" which remain undeleted within my note tree. These "new notes" clutter my workspace, scattered across various locations. I made this bulk deletion of these empty "new notes." Additionally, it generates warning messages for "new notes" that contain content, maybe we should change the title for those notes.

ea.delete_empty_note()

Install with pip egg link to make package change without reinstall.

python -m pip install --user -e .

The original OpenAPI document is here. You can open it with swagger editor.