Skip to main content

Importing Documents

The nogon import command collects related import tools under one command. Every import sends documents to a running Nogon server.

Service imports accept NOGON_IMPORT_* credentials and the corresponding legacy HISTER_IMPORT_* names. --api-token takes precedence, followed by the Nogon variable, then the Hister variable. An explicitly empty or blank value is treated as a missing credential and does not fall back. These source credentials are separate from the global --token used for the destination Nogon server.

Hister v0.16.0 uses the standalone hister import-browser command. To import browser history with that release, replace nogon import browser in the examples below with hister import-browser. The unified import command is available in rolling builds and stable releases newer than v0.16.0.

Available Import Sources

CommandSourceDefault label
nogon import file [INPUT...]Exports, saved pages, and file snapshotsimport or watched label
nogon import zim ARCHIVEKiwix ZIM archiveskiwix
nogon import sitemap FILE_OR_URLPages listed in XML sitemapssitemap
nogon import rss FEED_URLArticles linked from RSS or Atom feedsrss
nogon import browser [BROWSER] [DB_PATH]Browser history databasesbrowser
nogon import browser historyBrowser history with --browser and --dbbrowser
nogon import browser bookmarksFirefox, Chromium, and Ladybird bookmarksbookmarks
nogon import linkding INSTANCE_URLA Linkding instance through its HTTP APIlinkding
nogon import linkwarden INSTANCE_URLA Linkwarden instance through its HTTP APIlinkwarden
nogon import karakeep INSTANCE_URLA Karakeep instance through its HTTP APIkarakeep
nogon import raindropRaindrop.io through its HTTP APIraindrop
nogon import raindrop --input INPUT.csvA Raindrop.io CSV exportraindrop
nogon import readeck INSTANCE_URLA Readeck instance through its HTTP APIreadeck
nogon import readwiseReadwise Reader through its HTTP APIreadwise
nogon import shaarli INSTANCE_URLA Shaarli instance through its HTTP APIshaarli
nogon import wallabag INSTANCE_URLA wallabag instance through its HTTP APIwallabag

Use the global --server-url and --token flags when the destination Nogon server differs from your configured server or requires authentication.

Use --label LABEL with any import source to attach the same label to every imported document. Without this flag, labels stored in imported documents or resumed browser jobs are preserved. The default shown above is applied only when no label was supplied by the user or the imported document.

Use --ignore-rules with any import source to explicitly save submitted documents despite URL allow and skip rules. The saved override also protects them from allow and skip rules during nogon reindex. Browser imports bypass their initial URL rule filtering too. Sensitive content checks and source selection filters still apply. Documents skipped because they already exist are not changed.

nogon import file --ignore-rules export.json
nogon import browser bookmarks --ignore-rules --browser firefox

For persistent browser imports, pass --ignore-rules again when resuming with nogon index --job-id JOB_ID. The option applies to documents submitted during that invocation; it is not stored as a crawl job setting.

Nogon also limits each batch according to the byte limit advertised by the destination server. Documents are serialized before batching so stored HTML and other large fields are measured accurately. If another HTTP server imposes a smaller limit, Nogon splits a rejected batch and retries it automatically. A document that exceeds the limit by itself is reported with its URL, encoded size, and the server limit when known.

Importing Files

Use nogon import file with any number of files or directories:

Important: Use nogon import file to restore Nogon JSON exports, including exports in 7z archives, regardless of whether the server can access them.

For ordinary documents such as PDFs, notes, and text files, importing is only needed when the Nogon server cannot access the files directly. Otherwise, use local file indexing. Configure indexer.directories and restart the server to scan and watch those directories automatically.

nogon import file export.json page.html ~/Downloads/saved-pages

Supported inputs are:

InputBehavior
Nogon JSON exportRestores serialized documents without extracting their stored content again
7z archiveReads the first JSON export inside the archive
HTML or HTM page with a URLExtracts the canonical, OpenGraph, or Twitter URL
Other local fileExtracts supported content locally and creates a remote file snapshot
DirectoryImports matching files recursively

PDF, DOCX, Markdown, Org mode, HTML, and valid UTF 8 text use the same handlers as watched files. JSON that does not have the Nogon export array shape and HTML that has no source URL are also treated as file snapshots. HTML snapshots contain extracted body text and a page title, with the original HTML retained for previews.

Nogon JSON exports need a .json extension when importing. The export command appends .json when the output filename has no extension: nogon export backup writes backup.json, which you can restore with nogon import file backup.json. Existing backups with another extension or no extension should be renamed to end in .json before importing.

Use the original JSON file produced by nogon export. Each document must occupy one line starting with {, with array brackets and separating commas on their own lines. Compact or indented export layouts are rejected. An empty export may contain []. Each line must be smaller than 64 MiB; indexer.max_file_size_mb controls file snapshots and does not change this export limit. Parse errors identify the input file and line, including the entry name when reading a 7z archive.

ZIP, gzip, and other archive formats besides 7z must be extracted before importing their contents. Plain text files must use UTF 8 encoding.

With no input paths, the command recursively creates remote file snapshots from every configured watched directory. It applies the same file type, pattern, exclusion, hidden path, size, and label settings. Use this mode only when the command line client can read those directories but the server cannot:

nogon import file

You can also provide individual files or directories:

nogon import file ~/notes ~/Documents/report.pdf

Snapshot extraction happens in the command line process. Only the prepared document fields are sent through /api/add, including extracted text and any HTML preview content. By default, the command imports once and exits. Use --watch to keep updating snapshots while the command is active.

Remote file documents use a remote-file://SOURCE/absolute/path identity. The default source is the client hostname. Set a stable name when hostnames may change or when several clients have the same paths:

nogon import file --source alice-laptop ~/notes

To continuously import new and changed files from the client machine:

nogon import file --watch --source alice-laptop ~/notes

# Use the configured directory rules instead of explicit paths
nogon import file --watch --source alice-laptop

Watch mode performs an initial scan and continues until Ctrl+C or a termination signal. Explicit directories are watched recursively, including newly created directories. Explicit files are watched individually, including saves that replace the file. Directory filters, labels, size limits, destination ownership, and sensitive content checks apply throughout the session.

Watch mode handles remote file snapshots only. It skips Nogon JSON exports, 7z archives, and saved HTML pages with source URL metadata, including during the initial scan. Ordinary JSON and HTML without a source URL remain supported. Date filters cannot be combined with --watch.

--skip-existing applies only to the initial scan. Later changes replace existing snapshots. Temporary server failures are retried while the command runs; files that fail extraction or validation are tried again when they change. Import activity is logged and the selected output format contains a combined summary on exit. Its error count reports files with unresolved import failures.

Removing or renaming a source file does not delete its old snapshot, even when delete_on_remove is enabled. A renamed file discovered inside a watched directory is imported under its new path. Restarting the command scans all inputs again to pick up changes made while it was stopped. Pending retries are kept only in memory.

The following options apply to file imports:

FlagPurpose
--skip-existingKeep documents whose URL already exists in Nogon
--label LABELOverride stored labels and the default import label
--batch-size NSubmit at most 1 through 100 documents per request
--start-date YYYY-MM-DDImport documents added on or after the date
--end-date YYYY-MM-DDImport documents added on or before the date
--globalImport for all users when authenticated as an administrator
--user-id IDImport for one user when authenticated as an administrator
--source NAMESet the source namespace used in document URLs
--watchContinue importing new and changed remote file snapshots
--allow-sensitiveSkip sensitive content checks

Running the command again replaces documents with the same source and absolute path. --watch synchronizes file changes while active; source removals always retain the indexed snapshots.

The destination account and the --global or --user-id flags determine ownership. The user value on a watched directory is not resolved by this client side import.

Importing Kiwix Archives

Import HTML articles and plain text from downloaded .zim collections:

nogon import zim collection.zim --label reference

ZIM support is included in Nogon. Use a complete .zim file; combine split archives before importing. Large archives can require substantial memory, even when individual articles are small.

Nogon reads original page URLs and resolves relative addresses when enough source information is available. Relative article links use their target pages’ original URLs. Links whose destinations remain unknown are disabled.

Every document without an identifiable original URL is skipped with a warning. Warnings include the archive entry path and remain visible with JSON output or a restrictive log level. These documents count as skipped in the import summary.

If archive paths match the original website paths, you can supply a fallback base URL:

nogon import zim collection.zim --base-url https://example.org/docs/

Page URLs take priority over this fallback. The base must be an absolute HTTP or HTTPS URL without credentials, a query, or a fragment.

Reimporting the same URLs updates existing documents; --skip-existing keeps them. The usual import label, ownership, batch size, date, rule, sensitive content, and output options apply. Date filters use the archive publication date. indexer.max_file_size_mb limits each article, up to 32 MiB. Read or submission errors are reported and cause an unsuccessful exit after the remaining entries are processed.

Images, scripts, other assets, and redirect entries are not imported as documents. Saved previews do not reproduce embedded assets. Collections that require JavaScript rendering or media transcription may have little searchable text.

Importing Sitemaps

Use a sitemap to index a site’s listed pages without following links on those pages:

nogon import sitemap https://example.com/sitemap.xml
nogon import sitemap ./sitemap.xml
nogon import sitemap ./sitemap.xml.gz --label reference
nogon import sitemap - < sitemap.xml

The command accepts XML urlset files and sitemapindex files, including gzip compressed input. Index files are expanded by downloading their referenced sitemaps. Every loc must contain an absolute HTTP or HTTPS URL, including references inside a local index file. Duplicate page URLs and repeated sitemap references are processed once. Image and video extension URLs are not imported as pages.

The importer reads the complete sitemap collection before creating a persistent crawl job in the local Nogon database. Malformed XML, invalid URLs, or a failed sitemap download stop discovery without indexing a partial collection. Each XML file is limited to 50 MiB after decompression and 50,000 entries, following the Sitemap protocol. An import can read up to 50,000 distinct sitemap files. Empty collections are reported as errors.

Listed pages are fetched and submitted to the configured Nogon server. Existing documents are skipped by default; use --force to replace them. Sitemap metadata such as lastmod, priority, and changefreq does not control page fetching or search ranking. Sitemap discovery itself does not save page content or eliminate the need to fetch each page.

The following options apply to sitemap imports:

FlagPurpose
--label LABELReplace the default sitemap label
--forceFetch and replace pages that are already indexed
--backend http\|chromedp\|bidiSelect the backend for fetching listed pages
--backend-option KEY=VALUEConfigure the selected page backend
--proxy URL, --header KEY=VALUE, --cookie VALUEApply crawler proxy, header, and cookie settings
--delay SECONDS, --timeout SECONDS, --user-agent VALUEOverride crawler request settings
--no-robotsDisable robots checks for sitemaps and listed pages
--failed-urls FILEWrite failed page URLs to a file
--format text\|json\|jsonl\|csvSelect the result summary format
--global, --user-id IDSet destination ownership when authorized
--ignore-rulesBypass URL allow and skip rules for submitted pages
--allow-sensitiveSkip sensitive content checks

Sitemaps are always downloaded with HTTP, even when a browser backend fetches the listed pages. Crawler proxy, headers, cookies, user agent, timeout, and delay settings apply to sitemap requests too. Robots checks are enabled unless disabled in configuration or with --no-robots.

Once discovery finishes, the command prints a job ID. Inspect and resume that job using the existing crawl commands:

nogon crawl show JOB_ID
nogon crawl errors JOB_ID
nogon index --job-id JOB_ID

The stored job retains its page queue, label, and restriction to listed URLs. When resuming, supply any command line overrides for crawler settings, destination ownership, --force, --ignore-rules, or --allow-sensitive again. Interrupted sitemap discovery must be started again; only the page crawl is resumable.

Importing RSS and Atom Feeds

Provide the feed’s HTTP or HTTPS URL to import its linked articles:

nogon import rss https://example.com/feed.xml
nogon import rss https://example.com/atom.xml --label news
nogon import rss https://example.com/feed.xml --force

The command fetches each article’s full page and imports once, then exits. It does not subscribe to future updates or import the text embedded in the feed. Duplicate article URLs are processed once, and existing documents are skipped unless you pass --force. Entries without a usable HTTP or HTTPS article link are skipped. Relative links are resolved against the feed URL after redirects, or an explicit base URL in the feed.

The default label is rss. The sitemap import options also apply, including crawler settings, robots checks, ownership, and failed URL reports. Feeds are always downloaded over HTTP; --backend selects how articles are fetched. Feed downloads are limited to 16 MiB. Invalid, empty, or failed feeds stop the import before articles are queued.

The command prints a crawl job ID. Resume an interrupted article import with nogon index --job-id JOB_ID, supplying any crawler, ownership, or rule overrides again. Run the RSS import command again to discover new articles.

Importing Browser History

Browser history contains URLs and visit information, but it does not contain the page contents. Nogon reads the URLs from the browser database and fetches the pages before indexing them.

Automatic Detection

Run the command without arguments to detect supported browser databases in their standard locations:

nogon import browser

Automatic detection supports Firefox, Firefox Developer Edition, Zen, Waterfox, Chrome, Chromium, Brave, Vivaldi, Edge, Opera, and Ladybird.

The same history import is also available with named flags:

nogon import browser history
nogon import browser history --browser firefox
nogon import browser history --db ~/.mozilla/firefox/example.default/places.sqlite

Selecting a Browser or Database

You can provide a browser name, a database path, or both:

# Detect the Firefox database path
nogon import browser firefox

# Detect the browser type from a database
nogon import browser ~/.mozilla/firefox/example.default/places.sqlite

# Specify both values
nogon import browser firefox ~/.mozilla/firefox/example.default/places.sqlite

Firefox stores history in places.sqlite inside its profile directory. Chromium based browsers usually store it in a file named History inside their profile directory. Safari stores it in ~/Library/Safari/History.db.

When only a path is given, the browser is identified by the tables the database contains rather than by its filename. This matters because the filenames overlap: Safari and Ladybird both use History.db.

Safari

Safari is supported on macOS. It keeps a single history database per user, so there are no profile directories to choose between:

nogon import browser safari

Reading it requires Full Disk Access for the terminal or application running Nogon, granted under System Settings > Privacy & Security > Full Disk Access. Without it the import fails with a permission error naming the setting.

Use --min-visit N to import only URLs that have at least N recorded visits. Use --start-date YYYY-MM-DD to import only URLs whose most recent recorded visit is on or after that date:

nogon import browser --start-date 2025-01-01

The date filter uses timestamps from the browser database. The indexed document timestamp still describes when Nogon fetched the page.

Browser history documents receive the browser label by default. Use --label LABEL to replace it. Resumed browser import jobs reuse their stored label unless this flag is supplied again.

Importing Browser Bookmarks

Bookmark import reads saved bookmarks, then fetches the pages through the same crawl job used by history import.

nogon import browser bookmarks
nogon import browser bookmarks --browser firefox
nogon import browser bookmarks --browser chrome
nogon import browser bookmarks --db ~/.mozilla/firefox/example.default/places.sqlite
nogon import browser bookmarks --db ~/.config/google-chrome/Default/Bookmarks

Automatic detection covers Firefox, Firefox Developer Edition, Zen, Waterfox, Chrome, Chromium, Brave, Edge, Vivaldi, Opera, and Ladybird. Each browser is a separate bookmark source: Firefox-family places.sqlite, Chromium-family Bookmarks JSON, and Ladybird Bookmarks.json.

Allow and skip rules apply the same way they do for history import. A browser’s shipped default bookmarks follow these same rules.

Bookmark documents receive the bookmarks label by default. Use --label LABEL to replace it. --start-date is not supported, because it would drop bookmarks that have never been visited.

Bookmark imports use persistent crawl jobs named browser-bookmark-import-YYYY-MM-DD.

Resume and Inspect a Browser Import

History imports use persistent crawl jobs named browser-history-import-YYYY-MM-DD. Older browser-import-* history jobs still resume. Bookmark jobs are browser-bookmark-import-*. It is safe to interrupt the process and continue it later. Completed URLs remain completed, pending URLs resume, and failed URLs remain recorded for inspection.

nogon crawl list
nogon crawl show browser-history-import-YYYY-MM-DD
nogon crawl errors browser-history-import-YYYY-MM-DD
nogon crawl urls browser-history-import-YYYY-MM-DD

Add --count to nogon crawl urls when only the number of tracked URLs is needed. Use --status pending, --status failed, --status done, or --status skipped to filter the rows.

Browser Import Backends

The default HTTP backend is fast, but it cannot execute JavaScript. Select a browser based backend when a site requires client side rendering:

nogon import browser --backend chromedp

The supported backends are http, chromedp, and bidi. Backend options, request headers, and cookies can be supplied when necessary:

nogon import browser 
  --backend chromedp 
  --backend-option exec_path=/usr/bin/chromium 
  --proxy http://127.0.0.1:8080 
  --header "Accept-Language=en" 
  --cookie "session=abc; Domain=example.com"

The --backend-option, --header, and --cookie flags can be repeated. Use --proxy with an http:// or socks5:// URL. Cookies use Set-Cookie syntax and require a Domain attribute. See Website Crawler for all crawler settings and backend limitations.

Automated requests can be rejected by bot protection, expired sessions, removed pages, or network failures. Failed URLs remain visible through nogon crawl errors, but resuming the job does not retry them. Export those URLs into a new URL input job when you want to retry them. See Retrying Failed URLs.

Importing from Linkding

Copy the API token from the Linkding settings page, then store it in the environment before running the import:

export NOGON_IMPORT_LINKDING_TOKEN='your-linkding-token'
nogon import linkding https://linkding.example.com

You can use --api-token as a temporary override. The Linkding API token is separate from the global --token flag, which authenticates with the destination Nogon server. Prefer the environment variable so the Linkding token does not appear in shell history or process listings.

Incremental Linkding Imports

Every imported Linkding document receives source: linkding metadata. Nogon searches for metadata.source:linkding and reads the newest imported document timestamp before calling Linkding. If a previous import exists, the importer supplies that timestamp through the modified_since filter for both active and archived bookmarks. Otherwise, it requests every bookmark.

Deleted Linkding bookmarks are not removed from Nogon during an incremental import.

Linkding Data Mapping

Linkding valueNogon value
URLNormalized document URL
TitleTitle
Description, notes, and downloaded page contentSearchable text
Added dateAdded timestamp
Modification dateUpdated timestamp
FaviconDocument favicon
Tags, archive state, unread state, sharing, and IDDocument metadata
Archive snapshot and preview image URLsDocument metadata

Records without a URL are skipped because every Nogon document requires a URL. Active and archived pagination and batch submission are automatic.

Linkding stores bookmark metadata rather than complete copies of linked pages. Nogon therefore downloads every bookmarked page using the configured crawler backend and combines its extracted content with the stored description and notes.

Consult the Linkding API documentation when troubleshooting API access.

Importing from Linkwarden

Create an API token in Linkwarden, then store it in the environment before running the import:

export NOGON_IMPORT_LINKWARDEN_TOKEN='your-linkwarden-token'
nogon import linkwarden https://links.example.com

You can use --api-token as a temporary override. The Linkwarden API token is separate from the global --token flag, which authenticates with the destination Nogon server. Prefer the environment variable so the Linkwarden token does not appear in shell history or process listings.

Incremental Linkwarden Imports

Every imported Linkwarden document receives source: linkwarden metadata. Before requesting Linkwarden records, Nogon searches for metadata.source:linkwarden, sorts the results by update date, and reads the newest document’s updated timestamp.

When a previous result exists, the importer adds an after: filter to the Linkwarden search request so only newer records are fetched. When no previous result exists, it performs a complete import. Repeating the command therefore continues from the most recent Linkwarden import automatically.

Linkwarden Data Mapping

Linkwarden valueNogon value
URLNormalized document URL
NameTitle
Description and extracted text contentSearchable text
Import date, then creation dateAdded timestamp
Update dateUpdated timestamp
Tags, collection, source type, and IDDocument metadata

Records without a URL are skipped because every Nogon document requires a URL. Pagination and batch submission are automatic.

If a Linkwarden URL record has no extracted text content, Nogon downloads the page and extracts its contents before importing it. The configured crawler backend is used for these downloads. The crawler is initialized only when missing content is encountered and is reused for the rest of the import.

Importing from Karakeep

Karakeep was formerly named Hoarder. Create an API key in Karakeep, then store it in the environment before running the import:

export NOGON_IMPORT_KARAKEEP_TOKEN='your-karakeep-token'
nogon import karakeep https://karakeep.example.com

You can use --api-token as a temporary override. The Karakeep API token is separate from the global --token flag used for the destination Nogon server.

Incremental Karakeep Imports

Every imported Karakeep document receives source: karakeep metadata. Nogon searches for metadata.source:karakeep and reads the newest imported document timestamp before calling Karakeep. If a previous import exists, the importer uses Karakeep search with an after: date. Otherwise, it requests every bookmark.

Karakeep applies the after: search qualifier to the bookmark creation date. A bookmark created before the checkpoint and edited afterward might therefore require a complete import to refresh it.

Karakeep Data Mapping

Karakeep valueNogon value
Link URL or source URLNormalized document URL
Bookmark title, content title, or filenameTitle
Note, summary, description, and contentSearchable text
Creation dateAdded timestamp
Modification dateUpdated timestamp
Stored faviconDocument favicon
Tags, statuses, source, assets, and IDDocument metadata

For link bookmarks, Nogon extracts the stored Karakeep HTML when it is available. If stored HTML is absent or cannot be extracted, Nogon downloads the page with the selected crawler backend. Text and asset bookmarks use their stored content when they have a source URL.

Text and asset bookmarks without a source URL are skipped because every Nogon document requires a URL. Pagination and batch submission are automatic.

Consult the Karakeep API documentation when troubleshooting API access.

Importing from Readeck

Create an API token in the Readeck profile settings, then store it in the environment before running the import:

export NOGON_IMPORT_READECK_TOKEN='your-readeck-token'
nogon import readeck https://readeck.example.com

You can use --api-token as a temporary override. The Readeck API token is separate from the global --token flag used for the destination Nogon server. Prefer the environment variable so the source token does not appear in shell history or process listings.

Incremental Readeck Imports

Every imported Readeck document receives source: readeck metadata. Nogon searches for metadata.source:readeck and reads the newest imported document timestamp before calling Readeck. If a previous import exists, Nogon requests sync events from that timestamp. Otherwise, it requests every current bookmark.

Repeated update events are combined before content is requested. Deletion events are ignored because an import does not remove existing Nogon documents.

Readeck Data Mapping

Readeck valueNogon value
URLNormalized document URL
TitleTitle
Description, authors, and stored or downloaded page contentSearchable text
Creation dateAdded timestamp
Update dateUpdated timestamp
Stored site iconDocument favicon
Labels, authors, type, status, reading progress, and IDDocument metadata
Site, publication, image, thumbnail, and resource URLsDocument metadata

Nogon requests bookmark metadata and stored article HTML through the Readeck sync API. Readeck returns article bodies as HTML fragments, so Nogon wraps each fragment as a complete HTML document before extraction and storage. If stored HTML is absent or cannot be extracted, Nogon downloads the original URL with the selected crawler backend.

Article images keep absolute Readeck resource URLs. Searchable text and HTML remain stored in Nogon, but those images require the Readeck instance to remain available. Sync requests and Nogon batch submissions use the selected --batch-size.

Consult the API reference on the /api route of your Readeck instance or the Readeck documentation when troubleshooting API access.

Importing from Shaarli

Copy the API secret from the Shaarli administration page, then store it in the environment before running the import:

export NOGON_IMPORT_SHAARLI_SECRET='your-shaarli-api-secret'
nogon import shaarli https://shaarli.example.com

You can use --api-token as a temporary override. For Shaarli, this option accepts the API secret from the administration page. Nogon uses the secret to generate a short lived HS512 JWT for each API request. The secret itself is not sent to Shaarli. The global --token flag remains the access token for the destination Nogon server.

Incremental Shaarli Imports

Every imported Shaarli document receives source: shaarli metadata. Nogon searches for metadata.source:shaarli and reads the newest imported document timestamp before calling Shaarli.

If a previous import exists, Nogon requests Shaarli history since that timestamp and retrieves the current value of every created or updated Shaare. Repeated events for the same Shaare are combined. Deleted Shaares are ignored because an import does not remove existing Nogon documents. Without a previous result, Nogon requests every Shaare.

Shaarli Data Mapping

Shaarli valueNogon value
Link URL or text note permalinkNormalized document URL
TitleTitle
Description and downloaded page contentSearchable text
Creation dateAdded timestamp
Update dateUpdated timestamp
Tags, privacy, short URL, note status, and IDDocument metadata

Shaarli stores bookmark descriptions rather than complete copies of linked pages. Nogon therefore downloads every ordinary bookmark with the configured crawler backend and combines its extracted content with the stored description. Text notes use their description directly and keep a stable Shaarli permalink, so they are not downloaded.

Pagination and batch submission are automatic. Consult the Shaarli API documentation and Shaarli REST API authentication guide when troubleshooting API access.

Importing from wallabag

Obtain an OAuth access token from wallabag, then store it in the environment before running the import:

export NOGON_IMPORT_WALLABAG_TOKEN='your-wallabag-access-token'
nogon import wallabag https://wallabag.example.com

You can use --api-token as a temporary override. The wallabag access token is separate from the global --token flag, which authenticates with the destination Nogon server. Prefer the environment variable so the source token does not appear in shell history or process listings.

Incremental wallabag Imports

Every imported wallabag document receives source: wallabag metadata. Nogon searches for metadata.source:wallabag and reads the newest imported document timestamp before calling wallabag. If a previous import exists, Nogon supplies that timestamp through the wallabag since filter and requests entries in ascending update order. Otherwise, it requests every entry.

Deleted wallabag entries are not removed from Nogon during an incremental import.

wallabag Data Mapping

wallabag valueNogon value
URLNormalized document URL
TitleTitle
Stored article HTML, or downloaded page contentSearchable text
Creation dateAdded timestamp
Update dateUpdated timestamp
Tags, authors, status values, reading time, and source IDDocument metadata

Nogon extracts the article HTML already stored by wallabag and preserves it for offline previews. If the stored content is empty or cannot be extracted, Nogon downloads the original URL with the selected crawler backend. Pagination and batch submission are automatic.

Consult the wallabag OAuth documentation and wallabag API methods when troubleshooting API access.

Importing from Raindrop.io

Create an application in Raindrop’s integration settings, open its settings, and copy its Test token. Raindrop supports this token for accessing your own account without implementing an OAuth flow. See the Raindrop authentication documentation.

export NOGON_IMPORT_RAINDROP_TOKEN='your-raindrop-token'
nogon import raindrop

You can also supply the Raindrop token through --api-token. The global --token flag authenticates with the destination Nogon server.

Nogon requests all bookmarks outside Trash through Raindrop’s API. It preserves saved titles, creation and update dates, notes, highlights and their annotations, tags, favorites, and collection paths. The API does not include full page HTML in bookmark responses, so Nogon downloads linked pages using the configured crawler backend. If a page cannot be downloaded, its bookmark details are still imported and the failure is counted in the summary. Rate limit responses are retried up to three times using Raindrop’s retry or reset headers.

Repeated API Imports

Every imported document receives the raindrop label and source: raindrop metadata. API imports also receive raindrop_import: api metadata. Each API import reads all bookmarks and applies the requested date filters. Repeat the command to refresh bookmark details and page content or retry a failed import.

Use --skip-existing to keep every document whose normalized URL is already in Nogon and avoid downloading its content again:

nogon import raindrop --skip-existing

This also skips changed bookmarks that already exist. Deleted or trashed Raindrop bookmarks are not removed from Nogon.

Preserved Metadata

API imports retain raindrop_id, raindrop_collection_id, raindrop_folder, raindrop_type, raindrop_favorite, raindrop_broken, raindrop_cover, and raindrop_tags. The excerpt is stored as description; notes and highlights are stored as raindrop_note and raindrop_highlights. Structured highlight details, including their IDs, annotations, colors, and creation dates, are preserved in raindrop_highlight_details. Notes, excerpts, and highlights are also searchable alongside downloaded page content.

CSV Exports

Export your bookmarks as CSV using Raindrop’s export or backup controls, then import the downloaded file:

nogon import raindrop --input Raindrop.io-Export.csv

Use - to read the CSV from stdin:

cat Raindrop.io-Export.csv | nogon import raindrop --input -

CSV imports use the same content downloads and metadata fields as API imports. The optional CSV fields id and favorite are preserved as strings, while API imports use a numeric ID and a boolean favorite status. CSV exports supply a creation date but no update date, so both dates in Nogon use the creation date.

The CSV requires a header row with a url column containing HTTP or HTTPS URLs. Other columns are optional and may appear in any order. This also accepts a simple CSV containing only a url column. The created column accepts an ISO 8601 timestamp, a YYYY-MM-DD date, or a Unix timestamp in seconds. Missing dates use the import time. Quoted commas, quotes, and multiline notes are supported.

Rows without a URL are skipped. Invalid URLs, invalid dates, and rows with an incorrect number of fields are reported and skipped. Invalid CSV quoting stops the import after submitting previously prepared bookmarks.

To resume an interrupted import without downloading pages already in Nogon:

nogon import raindrop --input Raindrop.io-Export.csv --skip-existing

CSV imports need no Raindrop API credential. The --input option cannot be combined with --api-token. Raindrop API and CSV imports support the service import options below, including --label, date filters, and output formats. Individual failures result in exit status 2; source API failures, unreadable files, and invalid CSV headers or quoting result in exit status 1.

Importing from Readwise Reader

Get an access token from Readwise, then run:

export NOGON_IMPORT_READWISE_TOKEN='your-readwise-token'
nogon import readwise

You can use --api-token as a temporary override. The global --token flag authenticates with the destination Nogon server. The command connects to Readwise Reader directly and takes no instance URL.

Nogon requests documents from all Reader locations, including the feed and archive, through the Reader API. This imports Reader documents, including articles, videos, books, and PDFs. It does not use the original Readwise highlights API. Separate highlight and note records are skipped so they cannot overwrite the complete document at the same source URL. Notes attached to a document are included in its searchable text.

Readwise Data Mapping

Reader valueNogon value
source_url, or url when no source URL existsDocument URL
titleTitle
html_contentStored HTML and extracted searchable text
summary, notesSearchable text and metadata
created_at, updated_atAdded and updated timestamps
Document ID, Reader URL, author, tags, category, location, site, source, publication date, image URLreadwise_* metadata

Every imported document receives source: readwise metadata and the readwise label by default. Stored HTML is used first. If it is absent or cannot be extracted, Nogon downloads the original source URL using the configured crawler backend. Books and PDFs without a source URL use their Reader URL and stored HTML; if no content is available, their metadata is still imported. The importer does not download original EPUB or PDF attachments from Reader.

Pagination is automatic. Rate limit responses are retried up to three times, honoring Retry-After with a maximum wait of five minutes per retry. Each run scans the library again, allowing changed documents and previously failed imports to be retried. Use --skip-existing to keep URLs already indexed in Nogon:

nogon import readwise --skip-existing --label reading

Deleted Reader documents are not removed from Nogon. Readwise imports support the service import options below. Individual failures result in exit status 2; API or pagination failures result in exit status 1.

Service Import Options

The following options apply to Linkding, Linkwarden, Karakeep, Raindrop, Readeck, Readwise Reader, Shaarli, and wallabag imports. Raindrop CSV input does not use --api-token.

Service imports preserve favicon data supplied by the source. When it is absent, Nogon tries the favicon URL discovered while extracting the linked page, or the conventional /favicon.ico URL when no page icon is available. A favicon download failure does not stop the import.

FlagPurpose
--api-token TOKENOverride the source service credential for this invocation
--backend BACKENDDownload missing content with http, chromedp, or bidi
--backend-option KEY=VALUESet an option for the selected crawler backend
--proxy URLRoute content downloads through an HTTP or SOCKS5 proxy
--header KEY=VALUEAdd a request header when downloading missing content
--cookie COOKIEAdd a cookie when downloading missing content
--skip-existingKeep documents whose normalized URL already exists in Nogon
--label LABELOverride the default service source label
--batch-size NSubmit from 1 through 100 documents per request
--start-date YYYY-MM-DDImport documents added on or after the date
--end-date YYYY-MM-DDImport documents added on or before the date
--globalImport for all users when authenticated as an administrator
--user-id IDImport for one user when authenticated as an administrator

For example:

nogon import linkwarden https://links.example.com 
	--backend chromedp 
	--backend-option exec_path=/usr/bin/chromium 
	--skip-existing 
  --start-date 2024-01-01 
  --batch-size 25

Linkwarden provides /api/v1/search and Bearer token authentication. Consult the Linkwarden API documentation when troubleshooting API access.