## 1. Project Overview & Quickstart (go-vikunja/LICENSE) ## 1. Project Overview & Quickstart (go-vikunja/LICENSE) # LICENSE Open-source repository go-vikunja/LICENSE ### Repository Details - **Repository:** [go-vikunja/LICENSE](https://github.com/go-vikunja/LICENSE) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (go-vikunja/website) # Vikunja Homepage This project holds the source code for the Vikunja homepage at [vikunja.io](https://vikunja.io). ## 🚀 Project Structure Inside of your Astro project, you'll see the following folders and files: ```text / ├── public/ │ └── favicon.svg ├── src/ │ ├── components/ │ │ └── Card.astro │ ├── layouts/ │ │ └── Layout.astro │ └── pages/ │ └── index.astro └── package.json ``` Astro looks for `.astro` or `.md` files in the `src/pages/` directory. Each page is exposed as a route based on its file name. There's nothing special about `src/components/`, but that's where we like to put any Astro/React/Vue/Svelte/Preact components. Any static assets, like images, can be placed in the `public/` directory. ## 🧞 Commands All commands are run from the root of the project, from a terminal: | Command | Action | | :------------------------ | :----------------------------------------------- | | `pnpm install` | Installs dependencies | | `pnpm run dev` | Starts local dev server at `localhost:4321` | | `pnpm run build` | Build your production site to `./dist/` | | `pnpm run preview` | Preview your build locally, before deploying | | `pnpm run astro ...` | Run CLI commands like `astro add`, `astro check` | | `pnpm run astro -- --help` | Get help using the Astro CLI | ## 👀 Want to learn more? Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat). ## 2. Official Technical Reference & Guides (go-vikunja/website) ## File: README.md # Vikunja Homepage This project holds the source code for the Vikunja homepage at [vikunja.io](https://vikunja.io). ## 🚀 Project Structure Inside of your Astro project, you'll see the following folders and files: ```text / ├── public/ │ └── favicon.svg ├── src/ │ ├── components/ │ │ └── Card.astro │ ├── layouts/ │ │ └── Layout.astro │ └── pages/ │ └── index.astro └── package.json ``` Astro looks for `.astro` or `.md` files in the `src/pages/` directory. Each page is exposed as a route based on its file name. There's nothing special about `src/components/`, but that's where we like to put any Astro/React/Vue/Svelte/Preact components. Any static assets, like images, can be placed in the `public/` directory. ## 🧞 Commands All commands are run from the root of the project, from a terminal: | Command | Action | | :------------------------ | :----------------------------------------------- | | `pnpm install` | Installs dependencies | | `pnpm run dev` | Starts local dev server at `localhost:4321` | | `pnpm run build` | Build your production site to `./dist/` | | `pnpm run preview` | Preview your build locally, before deploying | | `pnpm run astro ...` | Run CLI commands like `astro add`, `astro check` | | `pnpm run astro -- --help` | Get help using the Astro CLI | ## 👀 Want to learn more? Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat). --- ## File: scripts/screenshots/README.md # Screenshot Automation Automated screenshot capture for the Vikunja website using Playwright. ## Prerequisites - Vikunja backend running on `:3456` with testing token enabled: ```yaml service: testingtoken: averyLongSecretToSe33dtheDB interface: ":3456" ``` - Vikunja frontend served on `:4173` (e.g. `pnpm build && pnpm preview` or `pnpm dev`) ## Usage ```bash # Install dependencies pnpm install # Run all screenshot specs pnpm screenshots # Run a specific spec pnpm screenshots -- specs/dashboard.spec.ts # Run in headed mode (see the browser) pnpm screenshots:headed # Run with Playwright inspector for debugging pnpm screenshots:debug ``` ## Spec Files ### Help page specs (`specs/*.spec.ts`) Generate screenshots for the end-user help documentation. Output: `src/assets/images/help/` ### Homepage carousel (`specs/homepage-carousel.spec.ts`) Generates 8 full-page (1280×900) screenshots used in the homepage image carousel. Output: `src/assets/images/vikunja/` | File | What it shows | |------|---------------| | `01-task-overview.png` | Dashboard with recently viewed projects + current tasks | | `02-task-list.png` | List view of project | | `03-task-gantt.png` | Gantt chart view | | `04-task-table.png` | Table view | | `05-task-kanban.png` | Kanban board with 3 buckets | | `06-task-detail.png` | Task detail with description and embedded image | | `07-quick-add.png` | Ctrl+K quick-add/search overlay | | `08-task-kanban-background.png` | Kanban board with project background image | ### Features page (`specs/features-page.spec.ts`) Generates 5 cropped content-area screenshots for the features page. Output: `src/assets/images/vikunja/features/` | File | What it shows | |------|---------------| | `task.png` | Task detail — title, breadcrumb, description, embedded image | | `list.png` | List view — task list with quick-add input, labels, assignees | | `gantt.png` | Gantt chart — timeline area | | `kanban.png` | Kanban board — buckets with task cards | | `table.png` | Table view — sortable columns | ### Flathub images After all specs run, `copy-flathub.ts` copies select homepage carousel images to `public/flathub-images/` for the Flathub app listing. ## Output Directories The `screenshot` fixture accepts a `dir` option to control the output subdirectory under `src/assets/images/`: ```ts await screenshot('my-shot', page, {dir: 'vikunja'}) // → src/assets/images/vikunja/my-shot.png await screenshot('my-shot', page, {dir: 'vikunja/features'}) // → src/assets/images/vikunja/features/my-shot.png await screenshot('my-shot', page) // → src/assets/images/help/my-shot.png (default) ``` ## Test Image Assets Two test images are stored in `support/` for use in specs that need task attachments or project backgrounds: - `test-image.jpg` — Used as an inline task attachment in task detail screenshots - `test-background.jpg` — Used as a project background in the kanban background screenshot To replace them, drop in new JPEG files with the same filenames and re-run the specs. ## Adding New Screenshots 1. Create a new spec file in `specs/` (or add to an existing one) 2. Use the `test` and `screenshot` fixtures from `support/fixtures.ts` 3. Use `createPopulatedProject()` from `support/seed-helpers.ts` to seed realistic data 4. Pass `{dir: 'your/subdir'}` to `screenshot()` for non-help output directories 5. Use locator targets for cropped shots of specific UI elements 6. Use `page.screenshot({ clip })` via the options parameter for custom-cropped areas 7. Run the spec to verify the screenshot looks correct --- ## File: scripts/README.md # Scripts ## publish-release Cross-posts a release blog post to Mastodon, Bluesky, GitHub Releases, Discourse, Matrix, LinkedIn, and Listmonk. ### Usage ``` node scripts/publish-release.js [--dry-run] ``` Example: ``` node scripts/publish-release.js 2.2.0 node scripts/publish-release.js 2.2.0 --dry-run ``` The script: 1. Finds the blog post at `src/content/changelog/release-.mdx` 2. Generates short (tweet-style) and LinkedIn content variants using `claude -p` 3. Opens `$EDITOR` to review and edit the generated content 4. Posts to each platform with a `[Y/n]` confirmation prompt 5. Prints a summary of all posted links `--dry-run` skips all API calls and prints what would be posted. ### Prerequisites - Node.js 20+ - [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli) (`claude` must be on PATH) - [GitHub CLI](https://cli.github.com/) (`gh`) authenticated for GitHub Releases ### API setup Create a `.env` file in the project root (already gitignored) with the credentials for each platform. Platforms with missing credentials are skipped automatically. ``` # Mastodon (social.linux.pizza) # Create an application at: https://social.linux.pizza/settings/applications # Required scopes: write:statuses MASTODON_TOKEN= # Bluesky # Create an app password at: https://bsky.app/settings/app-passwords BLUESKY_HANDLE= BLUESKY_APP_PASSWORD= # Discourse (community.vikunja.io) # Create an API key at: https://community.vikunja.io/admin/api/keys # Scope: topics (create) DISCOURSE_API_KEY= DISCOURSE_USERNAME= # Matrix (#vikunja:matrix.org) # Get an access token by logging in via the client-server API or from Element's settings MATRIX_ACCESS_TOKEN= MATRIX_HOMESERVER=https://matrix.org MATRIX_ROOM_ID= # Listmonk # Create an API user and token at: Admin -> Users # Required permissions: campaigns:manage LISTMONK_URL=https://your-listmonk-instance.example.com LISTMONK_API_USER= LISTMONK_API_TOKEN= # List ID to send the campaign to (find at Lists -> click list -> ID in URL) LISTMONK_LIST_ID= ``` GitHub Releases uses the `gh` CLI's existing authentication — no extra credentials needed. Run `gh auth status` to verify. LinkedIn has no API integration — the script prints the post text for you to copy and post manually. --- ## File: src/content/help/accessibility.mdx --- title: Accessibility slug: accessibility How to use Vikunja with a keyboard, adjust display and sound, and what works with screen readers, plus current limitations and how to report problems. --- import Callout from '../../components/Callout.astro'; Vikunja is built to work without a mouse and to adapt to how you read and hear the interface. This page covers the keyboard shortcuts, the display and sound settings, and what currently works with assistive technology, including the parts that are still rough. ## Using Vikunja with a keyboard You can reach and open every task without dragging, clicking, or pointing. The shortcuts below work throughout the app; press `?` at any time to open the shortcut reference for wherever you happen to be. ### On every page | Keys | Action | |------|--------| | `Ctrl+K` / `Cmd+K` | Open search and quick actions | | `Ctrl+E` / `Cmd+E` | Toggle the menu | | `?` | Open the keyboard shortcut reference | Search doubles as a command palette, so `Ctrl+K` also gets you to any task or project by name and lets you create new ones without leaving the page. ### Moving around These are chords: press the first key, release it, then press the second. | Keys | Goes to | |------|---------| | `g` then `o` | Overview | | `g` then `u` | Upcoming | | `g` then `p` | Projects | | `g` then `a` | Labels | | `g` then `m` | Teams | Inside a project, the same pattern switches [views](/help/views): `g` then `l` for List, `g` then `t` for Table, `g` then `k` for Kanban, and `g` then `g` for Gantt. ### In the List view | Keys | Action | |------|--------| | `j` | Highlight the next task | | `k` | Highlight the previous task | | `Enter` | Open the highlighted task | ### On a task When a task is open, single-key shortcuts jump straight to each field, so you never have to tab through the whole page to change one thing. | Keys | Action | |------|--------| | `t` | Mark done or undone | | `a` | Assign to a user | | `l` | Add labels | | `d` | Change the due date | | `Alt+R` / `Shift+R` | Manage reminders | | `e` | Edit the description | | `p` | Change the priority | | `c` | Change the color | | `f` | Add an attachment | | `r` | Edit related tasks | | `m` | Move to another project | | `s` | Toggle favorite | | `u` | Open the task's project | | `Ctrl+S` / `Cmd+S` | Save | | `Delete` / `Backspace` | Delete the task | Pressing `.` copies the task identifier; press it twice for the identifier and title, three times to add the URL. `Ctrl+.` / `Cmd+.` copies the task URL on its own. ### Doing without drag-and-drop Most things you can drag, you can also do from the keyboard: - **Move a task between Kanban buckets:** open the task and use the bucket dropdown in the breadcrumb line at the top. You don't need to drag the card. - **Reschedule in the Gantt view:** press `Tab` to land on a task bar, then use the Left and Right arrow keys to move it a day at a time. Separate buttons resize the start and end. Hold `Shift` with an arrow to extend the bar, or `Ctrl` / `Cmd` to shrink it. - **Set dates without the calendar grid:** in any date picker you can type the date directly, and there are separate month, year, and time controls if you'd rather step through them. - **Write descriptions by keyboard:** the rich-text editor is fully operable without a mouse. Markdown shortcuts work as you type (`#` for headings, `-` for a bullet, `1.` for a numbered list, `[]` for a checkbox), `Ctrl+S` / `Cmd+S` saves, and `Tab` moves focus out of the editor rather than trapping you in it. On Safari, `Tab` skips over links by default, so keyboard navigation can feel like it's missing stops. Turn on Safari → Settings → Advanced → "Press Tab to highlight each item" to Tab through everything, or hold `Option` while you press `Tab`. ## Display and sound - **Color scheme:** choose Light, Dark, or System (which follows your operating system) under Settings → General → Color Scheme. See [Settings](/help/settings#color-scheme). - **Zoom:** the layout reflows at 200% browser zoom without cutting off or hiding content, so you can enlarge text with your browser's own zoom. - **Completion sound:** the pop that plays when you finish a task can be turned off under Settings → General. ## Screen readers and assistive technology Vikunja is built with semantic structure that assistive technology can use: page landmarks, labeled controls, a skip-to-content link, and live-region announcements that read out the result of an action. The Gantt chart carries an ARIA description of what it shows. Images you add to a task description can be given alt text: select the image and choose **Alt text** in the bubble menu that appears. If you're picking a combination, VoiceOver works best with Safari, and NVDA with Chrome or Firefox. VoiceOver paired with Firefox announces headings and languages poorly; that's a limitation of the browser, not something we can fix from Vikunja's side. So far we've tested with automated checks and manual keyboard and accessibility-tree audits. We're expanding our screen reader testing, so if something reads badly in your reader, we want to hear about it. ## What doesn't work yet We'd rather tell you plainly than have you fight the interface: - **Reordering cards within a Kanban bucket** and **manually reordering the List view** are drag-and-drop only. The workaround is to sort instead: pick a [sort order](/help/views#sorting-the-list) and the tasks arrange themselves. - **Renaming a Kanban bucket** still needs a pointer. - Some color-contrast and announcement issues are still being fixed. A July 2026 accessibility audit kicked off a round of improvements, and the work is ongoing. ## Reporting an accessibility problem If something gets in your way, report it the same way you'd report any bug: - Open an issue on [GitHub](https://github.com/go-vikunja/vikunja) - Post on the [community forum](https://community.vikunja.io) - Email [hello@vikunja.io](mailto:hello@vikunja.io) Every one of these is text-based, so you can reach us however works for you. --- ## File: src/content/help/caldav.mdx --- title: CalDAV slug: caldav Sync tasks with external apps using CalDAV. Covers supported properties, URLs, and client compatibility. --- import Screenshot from '../../components/Screenshot.astro' import {VIKUNJA_CLOUD_LINK} from '../../helpers/vikunjaCloudLink' > **Warning:** The CalDAV integration is in an early alpha stage and has bugs. > It works well with some clients while having issues with others. > If you encounter issues, please [report them](https://code.vikunja.io/api/issues/new?body=[caldav]) Vikunja supports managing [tasks](/help/tasks) via the [caldav VTODO](https://tools.ietf.org/html/rfc5545#section-3.6.2) extension. You can find your CalDAV connection details in your [Settings](/help/settings) under the CalDAV tab. ## Authentication When you connect a CalDAV client, use your Vikunja **username** and one of the following as the password: - **Your account password** — the easiest option, and the one we recommend whenever it works for you. Local accounts, including those provisioned via LDAP, can use their normal password directly. If your account signs in through an external identity provider (OIDC) — for example on Vikunja Cloud — the CalDAV settings tab shows a hint asking you to use a dedicated token instead, because your password isn't stored in Vikunja. Passwords also don't work when two-factor authentication is enabled on your account. - **A dedicated CalDAV token** generated on the CalDAV settings tab. Use this if your account signs in via OIDC, or if you have two-factor authentication enabled. - **An [API token](/help/settings#api-tokens) with the CalDAV permission group**, available from Vikunja **2.3.0** onwards. Use the token value (it starts with `tk_`) as the password. This is handy if you want to manage all your automation credentials in one place, or if you want a single token to cover both CalDAV sync and API access. ## URLs All URLs are located under the `/dav` subspace. URLs are: * `/principals//`: Returns URLs for project discovery. *Use this URL when connecting a new client.* * `/projects/`: Used to manage [projects](/help/projects) * `/projects//`: Used to manage a single project * `/projects//`: Used to manage a task on a project ## Supported properties Vikunja currently supports the following properties: * `UID` * `SUMMARY` * `DESCRIPTION` * `PRIORITY` * `CATEGORIES` * `COMPLETED` * `CREATED` (only Vikunja → Client) * `DUE` ([Due date](/help/dates-and-reminders)) * `DURATION` * `DTSTAMP` * `DTSTART` * `LAST-MODIFIED` (only Vikunja → Client) * `RELATED-TO` (parent/child relations) * `RRULE` (Recurrence) (only Vikunja → Client) * `STATUS` (only `COMPLETED` status, used to mark tasks as done) * `VALARM` ([Reminders](/help/dates-and-reminders)) Vikunja **currently does not** support these properties: * `ATTACH` * `CLASS` * `COMMENT` * `CONTACT` * `GEO` * `LOCATION` * `ORGANIZER` (disabled) * `PERCENT-COMPLETE` * `RECURRENCE-ID` * `RESOURCES` * `SEQUENCE` * `URL` ## Tested Clients ### Working * [Evolution](https://wiki.gnome.org/Apps/Evolution/) * [OpenTasks](https://opentasks.app/) & [DAVx⁵](https://www.davx5.com/) * [Tasks (Android)](https://tasks.org/) * [Korganizer](https://apps.kde.org/korganizer/) ### Not working * [Thunderbird (68)](https://www.thunderbird.net/) * iOS CalDAV Sync (See [#753](https://kolaente.dev/vikunja/vikunja/issues/753)) --- ## File: src/content/help/dashboard.mdx --- title: Dashboard / Home Screen slug: dashboard The home screen you see after logging in. Shows upcoming tasks, a quick-add bar, and recently viewed projects. --- import Screenshot from '../../components/Screenshot.astro' After logging in, Vikunja takes you to the dashboard (home screen). This is your central hub for staying on top of tasks across all your projects. ## Overview From Vikunja **2.3.0** onwards, the greeting at the top rotates each day, so you will see a different phrasing for your current time of day each time you log in on a new day. ### Quick-add bar The input field at the top lets you create a new task without navigating to a specific project first. You can use [Quick Add Magic](/help/quick-add-magic) syntax here to set due dates, labels, priorities, and more directly from the input. Tasks created from the dashboard are added to your **default project**. See [Default project](#default-project) below to learn how to change it. ### Upcoming tasks Below the quick-add bar you will find all tasks from every project you have access to. They are sorted by due date: 1. **Overdue tasks** appear first. 2. Remaining tasks are sorted with the closest due date on top. This gives you a quick view of what needs attention right now and what is coming up next. ## Default project Tasks created from the dashboard go into your [default project](/help/projects#the-inbox-project). You can change which project is the default in your [Settings](/help/settings). ## Customizing the home screen filter By default, the dashboard shows all upcoming tasks from all projects. If you want to narrow this down, you can set a custom filter for the home screen: 1. [Create a saved filter](/help/saved-filters) that shows only the tasks you want to see. 2. Open your **[Settings](/help/settings)** and find the option to set a filter for the home screen. 3. Set the saved filter you created earlier to be shown on the dashboard. This is useful if you work across many projects but only want to see certain priorities or [labels](/help/labels) on your dashboard. ## Upcoming view (sidebar) The left sidebar contains an **Upcoming** entry that shows your tasks in a dedicated, full-page view. By default it displays incomplete tasks due between today and next week. Unlike the dashboard, the Upcoming view gives you controls to adjust what you see: - **Date range picker:** Choose a custom start and end date. For example, select the next two weeks to plan ahead. - **No dates checkbox:** Include tasks that have no due date set. - **Overdue checkbox:** Include tasks that are past their due date. Use this view when you want to focus on a specific time window without the other dashboard sections. ## Recently viewed projects Once you have opened a few [projects](/help/projects), the dashboard will also show a **recently viewed projects** section. This lets you quickly jump back to projects you have been working in without searching for them in the sidebar. If you prefer a cleaner dashboard, you can hide this section in your [Settings](/help/settings) under **Show last viewed projects on the overview page**. This setting is available from Vikunja **2.3.0** onwards. --- ## File: src/content/help/dates-and-reminders.mdx --- title: Dates & Reminders slug: dates-and-reminders --- import Screenshot from '../../components/Screenshot.astro' import Callout from '../../components/Callout.astro'; Tasks can have due dates, start and end dates, reminders, and repeating schedules. Here's how each one works. ## Due Date The due date is when a task must be finished. Once the due date passes, the task is considered overdue. Overdue tasks are highlighted so you can quickly spot what needs attention. If you've enabled it in the settings, you'll receive an email each morning with a list of the tasks that are overdue. Due dates are also used for sorting in the **Upcoming** view and on the **[dashboard](/help/dashboard)**, making it easy to see what is coming up next. ## Start and End Date Start and end dates define the window during which you plan to work on a task. For example, a report due March 31 (due date) might have a start date of March 20 and an end date of March 28, meaning you plan to do the work during that week. These dates are primarily used in the **[Gantt](/help/views#gantt-view)** view, where each task appears as a bar spanning from its start date to its end date on the timeline. ## Reminders You can set one or more reminders on any task. When a reminder triggers, you receive a [notification](/help/search-and-navigation#notifications) in the Vikunja UI. If you have email notifications enabled in your [settings](/help/settings), you will also receive an email. Reminders come in two types: - **Absolute reminders**: Set for a specific date and time (e.g. "remind me on March 5th at 9:00 AM"). - **Relative reminders**: Set relative to one of the task's date fields (due date, start date, or end date). For example, "remind me 1 hour before the due date" or "remind me 2 days before the start date". Relative reminders require the corresponding date field to be set on the task. For example, a reminder relative to the due date will not trigger if no due date is set. ## Repeating Tasks Tasks can repeat on a schedule. Vikunja supports the same kind of recurrence rules you know from calendar applications. Some examples: - Every day - Every week - Every month - Every 2 weeks on Tuesday - First Tuesday of the month When a repeating task is marked as done, Vikunja automatically creates the next occurrence based on the recurrence rule. ## Quick Add Magic Due dates, reminders, and repeating schedules can all be set directly when creating a task using Quick Add Magic. Instead of filling in fields manually, you can type everything in natural language right in the task title. For the full list of supported keywords and date formats, see [Quick Add Magic](/help/quick-add-magic). --- ## File: src/content/help/desktop.mdx --- title: Desktop App slug: desktop Sign in, use the quick-entry window, the system tray, and command-line flags in the Vikunja desktop app. --- import Callout from '../../components/Callout.astro'; import {VIKUNJA_CLOUD_LINK} from '../../helpers/vikunjaCloudLink'; Vikunja has a dedicated desktop application for Linux, macOS, and Windows. For download and installation instructions, see [Desktop Packages](/docs/setup/desktop). ## Logging in The OAuth-based desktop login is available from Vikunja **2.3.0** onwards. The first time you open the desktop app, you'll be asked to pick which server to connect to: - **Vikunja Cloud:** connect to the hosted Vikunja Cloud service. - **Try Demo:** connect to `try.vikunja.io`, the public demo instance. - **Custom Server:** enter the URL of your own self-hosted Vikunja instance. After you pick a server, the desktop app opens your browser to sign in. If your instance uses an external login provider (for example a single sign-on system), you can sign in with it here as well. Once you approve the sign-in, the browser hands you back to the desktop app and you're signed in. ## Quick-entry window The quick-entry window is available from Vikunja **2.3.0** onwards. The desktop app has a dedicated **quick-entry window**: a small popup you can open from anywhere on your system to add a task without first switching to the main Vikunja window. It's the same quick-entry overlay you can already open from inside Vikunja with `Ctrl` / `Cmd` + `K` — the desktop app just makes it available as a standalone, always-on-top window so you can reach it even when Vikunja isn't focused. ### Opening the popup Press the global shortcut to open the popup. The default is `Ctrl` + `Shift` + `A` (or `Cmd` + `Shift` + `A` on macOS). You can change the shortcut in **Settings > General**, under the Desktop section. Click the shortcut recorder and press the key combination you want to use. You can also open the popup from the [system tray](#system-tray) or by launching the app with the [`--quick-entry`](#command-line-flags) flag. ### Creating a task The popup uses the same quick-entry interface as the [dashboard quick-add bar](/help/dashboard#quick-add-bar), so you can use [Quick Add Magic](/help/quick-add-magic) to set due dates, labels, priorities, assignees, and the target project while you type. - **Enter** creates the task and closes the popup. - **`Ctrl`** / **`Cmd`** + **Enter** creates the task and opens it in the main Vikunja window. - **Esc** closes the popup without creating a task. ## System tray The desktop app places an icon in your system tray with these entries: - **Show Vikunja:** open or focus the main window. - **Quick Add Task:** open the [quick-entry window](#quick-entry-window). The current global shortcut is shown next to the menu item. - **Quit:** close the app entirely. ## Command-line flags - `--quick-entry`: launch the app and immediately open the [quick-entry window](#quick-entry-window). If Vikunja is already running, this opens the popup in the existing instance instead of starting a second one. This is useful if you want to bind your own shortcut or launcher to the quick-entry window. --- ## File: src/content/help/filters.mdx --- title: Filters slug: filters Filter tasks by due date, priority, labels, assignees, and more using Vikunja's query syntax. --- import Screenshot from '../../components/Screenshot.astro' import Callout from '../../components/Callout.astro'; import DateMathExamples from '../../components/partials/DateMathExamples.astro'; Filters let you narrow down your task list so you only see what matters right now. Instead of scrolling through everything, you write a short query and Vikunja shows only the matching tasks. ## Common examples Copy any of these into a filter field to try it out: | | | |-----------------------------------------|-------------------------------------------| | `done = false` | All undone tasks | | `dueDate < now` | Overdue tasks | | `dueDate > now && dueDate < now+7d` | Tasks due in the next 7 days | | `done = false && priority >= 3` | Undone tasks with high priority (3+) | | `assignees in currentUser` | Tasks assigned to you | | `labels in urgent` | Tasks with the "urgent" label | | `labels in urgent, logistics` | Tasks labeled "urgent" or "logistics" | | `done = false && dueDate < now` | Undone overdue tasks | You can combine any of these patterns. For example, undone high-priority tasks due this week: ``` done = false && priority >= 3 && dueDate > now && dueDate < now+7d ``` ## Where to use filters - **[Views](/help/views):** Add a filter to any view so it only shows matching tasks. - **[Saved filters](/help/saved-filters):** Create a reusable filter that appears in your sidebar and works across all your projects. - **[Dashboard](/help/dashboard):** Set a saved filter to control which tasks appear on your home screen. **"Include Tasks which don't have a value set"** is on by default. A filter like `assignees in sarah` will also return tasks with *no* assignee. Disable this toggle in the filter settings if you only want tasks that have a value. ## How to write a filter A filter query has three parts: a **field**, an **operator**, and a **value**. ``` priority >= 3 ``` - `priority` is the field (what you are checking) - `>=` is the operator (how to compare) - `3` is the value (what to compare against) To combine conditions, use `&&` (and) or `||` (or): ``` done = false && priority >= 3 ``` Use parentheses to group conditions: ``` (priority = 1 || priority = 2) && dueDate <= now ``` The filter editor offers autocomplete for field names, label names, usernames, and project names as you type. ### Fields | | | |---------------|-----------------------------------------------------------------------------------------------| | `done` | Whether the task is completed (`true` or `false`) | | `priority` | Priority level (1 to 5) | | `percentDone` | Completion percentage (0 to 100) | | `dueDate` | The [due date](/help/dates-and-reminders) | | `startDate` | The [start date](/help/dates-and-reminders) | | `endDate` | The [end date](/help/dates-and-reminders) | | `doneAt` | When the task was completed | | `assignees` | The [assignees](/help/tasks#assignees) | | `labels` | The [labels](/help/labels) on the task | | `project` | The [project](/help/projects) (only in [saved filters](/help/saved-filters)) | | `reminders` | The [reminders](/help/dates-and-reminders) set on the task | | `created` | When the task was created | | `updated` | When the task was last updated | Strings with spaces or special characters must be wrapped in quotes: `"2024-03-11"`, `"waiting on others"`. ### Operators | | | |----------|----------------------------------------------------| | `=` | Equal to | | `!=` | Not equal to | | `>` | Greater than | | `>=` | Greater than or equal to | | `<` | Less than | | `<=` | Less than or equal to | | `like` | Matches a pattern (use `%` as wildcard) | | `in` | Matches any value in a comma-separated list | | `not in` | Does not match any value in a comma-separated list | ## Relative dates Instead of typing a fixed date, use `now` so your filter stays current automatically. Add or subtract time from `now` using units like `d` (days), `w` (weeks), or `M` (months): | | | |--------------------|----------------------------------| | `now` | Right now | | `now+1d` | Tomorrow | | `now-1d` | Yesterday | | `now+7d` | One week from now | | `now+1M` | One month from now | Use `/d` to round down to the start of the day, which is useful for "today" or "this week" filters: | | | |--------------------|----------------------------------| | `now/d` | Start of today | | `now+7d/d` | Start of the day, 7 days from now | ### All time units | | | |-----|---------| | `s` | Seconds | | `m` | Minutes | | `h` | Hours | | `d` | Days | | `w` | Weeks | | `M` | Months | | `y` | Years | ## API reference If you use filters through the Vikunja API rather than the web UI, see the [Filter API Reference](/docs/filters) for field names, query parameters, and other differences. --- ## File: src/content/help/import-and-export.mdx --- title: Import & Export slug: import-and-export Export your Vikunja data or import tasks from CSV files, TickTick, WeKan, Planka, Todoist, Trello, and Microsoft To Do. --- import Screenshot from '../../components/Screenshot.astro' import Callout from '../../components/Callout.astro'; Vikunja lets you export all of your data and import tasks from other services, making it easy to back up your work or migrate from another tool. ## Export You can export all your data from Vikunja, including [projects](/help/projects), [tasks](/help/tasks), attachments, and more. To start an export: 1. Open your **[Settings](/help/settings)** and navigate to the **Data Export** section. 2. Confirm your password to proceed. If you are using third-party authentication (for example, through Vikunja Cloud), you will see a confirmation step instead of a password prompt. Once confirmed, Vikunja will generate a ZIP file containing all of your data. You can download this file and keep it as a backup or use it to re-import your data into Vikunja later. ## Import To import data into Vikunja: 1. Open your **[Settings](/help/settings)** and navigate to the **Import** tab. 2. Select the source you want to import from. 3. Follow the on-screen steps to complete the import. Vikunja supports importing from the following sources: - **Vikunja export:** Re-import a previously exported ZIP file. - **CSV:** Import tasks from any CSV file with custom column mapping. - **TickTick** - **WeKan** (available from version 2.3.0) - **Planka** (available from version 2.6.0) - **Todoist** - **Trello** - **Microsoft To Do** You can also sync tasks with external apps using [CalDAV](/help/caldav). ### Importing from CSV This feature is available from Vikunja **2.3.0** onwards (or unstable builds). The CSV import lets you bring tasks into Vikunja from any spreadsheet or tool that can export CSV files. It works in three steps: 1. **Upload your CSV file.** Select a `.csv` or `.txt` file. Vikunja will auto-detect the delimiter, date format, and column mappings. 2. **Review and adjust the mapping.** Each column in your file can be mapped to a task attribute: title, description, due date, start date, end date, priority, labels, project, reminder, or set to "ignore". The preview below the mapping updates automatically as you change settings. 3. **Import.** Once you're happy with the preview, click "Import Tasks" to create all tasks in Vikunja. #### Parsing options You can adjust these settings if the auto-detection didn't get it right: - **Delimiter:** Comma, semicolon, tab, or pipe. - **Date format:** Choose the format that matches dates in your file (e.g. YYYY-MM-DD, DD/MM/YYYY, MM/DD/YYYY, etc.). - **Skip rows:** Skip a number of rows at the top of the file if they contain metadata or headers that aren't part of your task data. #### Column mapping At least one column must be mapped to **Title** for the import to work. All other attributes are optional: - **Labels** are parsed as comma-separated values within a single column. - **Priority** accepts numbers (0–5) or text like "low", "medium", "high", "urgent". - **Done** accepts values like "true", "yes", "1", "done", or "completed". - **Project** groups tasks into sub-projects. If no project column is mapped, or all tasks have the same project value, they are imported into a single "Imported from CSV" project. ### Importing from WeKan This feature is available from Vikunja **2.3.0** onwards (or unstable builds). To import a WeKan board, first export it as JSON in WeKan (board menu > Export board > JSON), then select the WeKan icon on the import page and upload the file. Each board export creates one Vikunja project. Lists become kanban buckets, cards become tasks, and labels, checklists, comments, and dates are all preserved. ### Importing from Planka This feature is available from Vikunja **2.6.0** onwards (or unstable builds). Vikunja imports directly from a running Planka instance (version 2 or later). There is no file to export. Select the Planka icon on the import page, enter the URL of your Planka instance and choose how Vikunja should log in: - **API key:** A Planka administrator must create an API key for your account. Copying a token from your browser does not work. - **Username and password:** Only works for local Planka accounts without two-factor authentication that have logged in to Planka at least once. Accounts using single sign-on need an API key. Your credentials are only used for this import and are not stored. Vikunja imports all projects and boards you have access to. A Planka project with a single board becomes one Vikunja project; a project with several boards becomes a parent project with one child project per board. Lists become kanban buckets, cards become tasks, and labels, due dates, comments, and file attachments are preserved. Archived and closed cards are imported as done tasks; trashed cards are skipped. Checklists and custom fields are added to the task description. Assignees and board members are not imported. If your Planka instance runs on a private network, the administrator of your Vikunja instance may need to allow outgoing requests to non-routable addresses for the import to reach it.