Skip to content

Add document list filters #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
NickChristensen merged 3 commits into from
Jan 29, 2026
Merged

Add document list filters #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
38becc2
Fix yaml parsing in paperless-ngx-api skill
NickChristensen Jan 28, 2026
a2a3469
Add document date range flags
NickChristensen Jan 29, 2026
b27a33c
Add document list filters
NickChristensen Jan 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .codex/skills/paperless-ngx-api/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: paperless-ngx-api
description: Use when working with the Paperless-ngx REST API: looking up endpoints, request/response shapes, auth requirements, filtering/pagination, or generating example requests/responses from the OpenAPI spec. Trigger for tasks involving Paperless-ngx API integrations, client code, curl examples, or schema details.
description: Use when working with the Paperless-ngx REST API; looking up endpoints, request/response shapes, auth requirements, filtering/pagination, or generating example requests/responses from the OpenAPI spec. Trigger for tasks involving Paperless-ngx API integrations, client code, curl examples, or schema details.
---

# Paperless Ngx Api
Expand Down Expand Up @@ -44,4 +44,5 @@ Common `yq` snippets (adjust selectors based on the spec structure):
## Resources

### references/

- `paperless-ngx-rest-api.yaml` (OpenAPI spec)
84 changes: 57 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -284,11 +284,9 @@ USAGE
[--sort <value>]

FLAGS
--id-in=<value>... Filter by id list (repeatable or comma-separated)
--name-contains=<value> Filter by name substring
--page=<value> Page number to fetch
--page-size=<value> [default: disable pagination, all results] Number of results per page
--sort=<value> Sort results by the provided field
--page=<value> Page number to fetch
--page-size=<value> [default: disable pagination, all results] Number of results per page
--sort=<value> Sort results by the provided field

GLOBAL FLAGS
--date-format=<value> [default: yyyy-MM-dd, env: PPLS_DATE_FORMAT] Format output dates using a template.
Expand All @@ -301,6 +299,10 @@ ENVIRONMENT FLAGS
--hostname=<value> [env: PPLS_HOSTNAME] Paperless-ngx base URL
--token=<value> [env: PPLS_TOKEN] Paperless-ngx API token

FILTER FLAGS
--id-in=<value>... Filter by id list (repeatable or comma-separated)
--name-contains=<value> Filter by name substring

DESCRIPTION
List correspondents

Expand Down Expand Up @@ -461,11 +463,9 @@ USAGE
[--sort <value>]

FLAGS
--id-in=<value>... Filter by id list (repeatable or comma-separated)
--name-contains=<value> Filter by name substring
--page=<value> Page number to fetch
--page-size=<value> [default: disable pagination, all results] Number of results per page
--sort=<value> Sort results by the provided field
--page=<value> Page number to fetch
--page-size=<value> [default: disable pagination, all results] Number of results per page
--sort=<value> Sort results by the provided field

GLOBAL FLAGS
--date-format=<value> [default: yyyy-MM-dd, env: PPLS_DATE_FORMAT] Format output dates using a template.
Expand All @@ -478,6 +478,10 @@ ENVIRONMENT FLAGS
--hostname=<value> [env: PPLS_HOSTNAME] Paperless-ngx base URL
--token=<value> [env: PPLS_TOKEN] Paperless-ngx API token

FILTER FLAGS
--id-in=<value>... Filter by id list (repeatable or comma-separated)
--name-contains=<value> Filter by name substring

DESCRIPTION
List custom fields

Expand Down Expand Up @@ -636,11 +640,9 @@ USAGE
[--sort <value>]

FLAGS
--id-in=<value>... Filter by id list (repeatable or comma-separated)
--name-contains=<value> Filter by name substring
--page=<value> Page number to fetch
--page-size=<value> [default: disable pagination, all results] Number of results per page
--sort=<value> Sort results by the provided field
--page=<value> Page number to fetch
--page-size=<value> [default: disable pagination, all results] Number of results per page
--sort=<value> Sort results by the provided field

GLOBAL FLAGS
--date-format=<value> [default: yyyy-MM-dd, env: PPLS_DATE_FORMAT] Format output dates using a template.
Expand All @@ -653,6 +655,10 @@ ENVIRONMENT FLAGS
--hostname=<value> [env: PPLS_HOSTNAME] Paperless-ngx base URL
--token=<value> [env: PPLS_TOKEN] Paperless-ngx API token

FILTER FLAGS
--id-in=<value>... Filter by id list (repeatable or comma-separated)
--name-contains=<value> Filter by name substring

DESCRIPTION
List document types

Expand Down Expand Up @@ -854,15 +860,37 @@ List documents
```
USAGE
$ ppls documents list [--date-format <value>] [--header <value>...] [--hostname <value>] [--plain | --json |
--table] [--token <value>] [--id-in <value>... | --name-contains <value>] [--page <value> --page-size <value>]
[--sort <value>]
--table] [--token <value>] [--page <value> --page-size <value>] [--sort <value>] [--added-after YYYY-MM-DD|ISO-8601
| [--id-in <value>... | --name-contains <value>]] [--added-before YYYY-MM-DD|ISO-8601 | ] [--created-after
YYYY-MM-DD|ISO-8601 | ] [--created-before YYYY-MM-DD|ISO-8601 | ] [--modified-after YYYY-MM-DD|ISO-8601 | ]
[--modified-before YYYY-MM-DD|ISO-8601 | ] [--no-correspondent | [--correspondent <value>... | ] |
[--correspondent-not <value>... | ] | ] [--no-document-type | [--document-type <value>... | ] | [--document-type-not
<value>... | ] | ] [--no-tag | --tag <value>... | --tag-all <value>... | --tag-not <value>... | ]

FLAGS
--id-in=<value>... Filter by id list (repeatable or comma-separated)
--name-contains=<value> Filter by name substring
--page=<value> Page number to fetch
--page-size=<value> [default: disable pagination, all results] Number of results per page
--sort=<value> Sort results by the provided field
--page=<value> Page number to fetch
--page-size=<value> [default: disable pagination, all results] Number of results per page
--sort=<value> Sort results by the provided field

FILTER FLAGS
--added-after=YYYY-MM-DD|ISO-8601 Filter by added date (YYYY-MM-DD) or datetime (ISO 8601) >= value
--added-before=YYYY-MM-DD|ISO-8601 Filter by added date (YYYY-MM-DD) or datetime (ISO 8601) <= value
--correspondent=<value>... Filter by correspondent ids (repeatable or comma-separated)
--correspondent-not=<value>... Exclude correspondent ids (repeatable or comma-separated)
--created-after=YYYY-MM-DD|ISO-8601 Filter by created date (YYYY-MM-DD) or datetime (ISO 8601) >= value
--created-before=YYYY-MM-DD|ISO-8601 Filter by created date (YYYY-MM-DD) or datetime (ISO 8601) <= value
--document-type=<value>... Filter by document type ids (repeatable or comma-separated)
--document-type-not=<value>... Exclude document type ids (repeatable or comma-separated)
--id-in=<value>... Filter by id list (repeatable or comma-separated)
--modified-after=YYYY-MM-DD|ISO-8601 Filter by modified date (YYYY-MM-DD) or datetime (ISO 8601) >= value
--modified-before=YYYY-MM-DD|ISO-8601 Filter by modified date (YYYY-MM-DD) or datetime (ISO 8601) <= value
--name-contains=<value> Filter by name substring
--no-correspondent Filter documents with no correspondent
--no-document-type Filter documents with no document type
--no-tag Filter documents with no tags
--tag=<value>... Filter by tag ids (repeatable or comma-separated, OR)
--tag-all=<value>... Filter by tag ids (repeatable or comma-separated, AND)
--tag-not=<value>... Exclude tag ids (repeatable or comma-separated)

GLOBAL FLAGS
--date-format=<value> [default: yyyy-MM-dd, env: PPLS_DATE_FORMAT] Format output dates using a template.
Expand Down Expand Up @@ -1094,11 +1122,9 @@ USAGE
[--sort <value>]

FLAGS
--id-in=<value>... Filter by id list (repeatable or comma-separated)
--name-contains=<value> Filter by name substring
--page=<value> Page number to fetch
--page-size=<value> [default: disable pagination, all results] Number of results per page
--sort=<value> Sort results by the provided field
--page=<value> Page number to fetch
--page-size=<value> [default: disable pagination, all results] Number of results per page
--sort=<value> Sort results by the provided field

GLOBAL FLAGS
--date-format=<value> [default: yyyy-MM-dd, env: PPLS_DATE_FORMAT] Format output dates using a template.
Expand All @@ -1111,6 +1137,10 @@ ENVIRONMENT FLAGS
--hostname=<value> [env: PPLS_HOSTNAME] Paperless-ngx base URL
--token=<value> [env: PPLS_TOKEN] Paperless-ngx API token

FILTER FLAGS
--id-in=<value>... Filter by id list (repeatable or comma-separated)
--name-contains=<value> Filter by name substring

DESCRIPTION
List tags

Expand Down
2 changes: 1 addition & 1 deletion src/base-command.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ export type ApiFlags = {
token: string
}

type QueryParams = Record<string, number | string | string[] | undefined>
type QueryParams = Record<string, number | number[] | string | string[] | undefined>

type ResolvedGlobalFlags = ApiFlags & {
dateFormat: string
Expand Down
Loading