Skip to content

armgit / papra

Public Imported from GitHub
0

The minimalistic document archiving platform.

feat(cli): added cli documentation (#275)

Corentin Thomasset9b72aa886cc7
diff --git a/apps/docs/package.json b/apps/docs/package.json
index ebe2413e..cf6e7e0c 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -17,8 +17,8 @@
"typecheck": "tsc --noEmit"
},
"dependencies": {
- "@astrojs/starlight": "^0.34.1",
- "astro": "^5.7.5",
+ "@astrojs/starlight": "^0.34.2",
+ "astro": "^5.7.10",
"sharp": "^0.32.5",
"starlight-links-validator": "^0.16.0",
"starlight-theme-rapide": "^0.5.0",
diff --git a/apps/docs/src/content/docs/04-resources/01-cli.mdx b/apps/docs/src/content/docs/04-resources/01-cli.mdx
new file mode 100644
index 00000000..75a63b38
--- /dev/null
+++ b/apps/docs/src/content/docs/04-resources/01-cli.mdx
@@ -0,0 +1,89 @@
+---
+title: CLI Documentation
+description: Learn how to use the Papra CLI to interact with your Papra instance from the command line.
+slug: resources/cli
+---
+
+The Papra CLI is a command-line interface tool that helps you interact with the Papra platform from your terminal.
+
+## Installation
+
+For the moment, the CLI is only available as an NPM package.
+
+```bash
+# using pnpm
+pnpm i -g @papra/cli
+
+# or using npm
+npm i -g @papra/cli
+
+# or using yarn
+yarn add -g @papra/cli
+```
+
+The CLI will be installed globally, so you can use it from anywhere in your system with the `papra` command.
+
+## Configuration
+
+Before using the CLI, you need to configure it with your API credentials.
+
+### Initial Setup
+
+To initialize the configuration, run:
+
+```bash
+papra config init
+```
+
+This command will prompt you for:
+- **Instance URL**: Your Papra instance URL (e.g., `https://api.papra.app`)
+- **API Key**: Your personal API key (can be created in your User Settings)
+
+### Managing Configuration
+
+You can manage your configuration using the following commands:
+
+- `papra config list`: View your current configuration
+- `papra config set api-key`: Set or update your API key
+- `papra config set api-url`: Set or update your instance URL
+- `papra config set default-org-id`: Set a default organization ID
+
+### Organization IDs
+
+Since Papra supports multiple organizations, you may need to specify the organization ID when importing documents for example. If want, you can set a default organization ID in your configuration.
+
+```bash
+papra config set default-org-id <organization-id>
+papra documents import <file-path>
+
+# or
+papra documents import -o <organization-id> <file-path>
+```
+
+## Available Commands
+
+### Importing documents
+
+The `import` command allows you to import a document into your Papra organization.
+
+```bash
+papra documents import -o <organization-id> <file-path>
+```
+
+## Getting Help
+
+For more information about any command, you can use the `--help` flag:
+
+```bash
+papra --help
+papra config --help
+papra documents --help
+```
+
+
+## About the CLI
+
+The CLI is built using the [citty](https://github.com/unjs/citty) framework and the [Papra TS SDK](https://github.com/papra-hq/papra/tree/main/packages/api-sdk).
+
+
+
diff --git a/apps/docs/src/content/navigation.ts b/apps/docs/src/content/navigation.ts
index e9e6b5e0..25ea6c48 100644
--- a/apps/docs/src/content/navigation.ts
+++ b/apps/docs/src/content/navigation.ts
@@ -35,6 +35,10 @@ export const sidebar: StarlightUserConfig['sidebar'] = [
{
label: 'Resources',
items: [
+ {
+ label: 'CLI Documentation',
+ slug: 'resources/cli',
+ },
{
label: 'Security Policy',
link: 'https://github.com/papra-hq/papra/blob/main/SECURITY.md',
diff --git a/packages/cli/README.md b/packages/cli/README.md
new file mode 100644
index 00000000..e1f82617
--- /dev/null
+++ b/packages/cli/README.md
@@ -0,0 +1,81 @@
+# Papra CLI
+
+The Papra CLI is a command-line interface tool that helps you interact with the Papra platform from your terminal.
+
+## Installation
+
+For the moment, the CLI is only available as an NPM package.
+
+```bash
+# using pnpm
+pnpm i -g @papra/cli
+
+# or using npm
+npm i -g @papra/cli
+
+# or using yarn
+yarn add -g @papra/cli
+```
+
+The CLI will be installed globally, so you can use it from anywhere in your system with the `papra` command.
+
+## Configuration
+
+Before using the CLI, you need to configure it with your API credentials.
+
+### Initial Setup
+
+To initialize the configuration, run:
+
+```bash
+papra config init
+```
+
+This command will prompt you for:
+- **Instance URL**: Your Papra instance URL (e.g., `https://api.papra.app`)
+- **API Key**: Your personal API key (can be created in your User Settings)
+
+### Managing Configuration
+
+You can manage your configuration using the following commands:
+
+- `papra config list`: View your current configuration
+- `papra config set api-key`: Set or update your API key
+- `papra config set api-url`: Set or update your instance URL
+- `papra config set default-org-id`: Set a default organization ID
+
+### Organization IDs
+
+Since Papra supports multiple organizations, you may need to specify the organization ID when importing documents for example. If want, you can set a default organization ID in your configuration.
+
+```bash
+papra config set default-org-id <organization-id>
+papra documents import <file-path>
+
+# or
+papra documents import -o <organization-id> <file-path>
+```
+
+## Available Commands
+
+### Importing documents
+
+The `import` command allows you to import a document into your Papra organization.
+
+```bash
+papra documents import -o <organization-id> <file-path>
+```
+
+## Getting Help
+
+For more information about any command, you can use the `--help` flag:
+
+```bash
+papra --help
+papra config --help
+papra documents --help
+```
+
+## About the CLI
+
+The CLI is built using the [citty](https://github.com/unjs/citty) framework and the [Papra TS SDK](https://github.com/papra-hq/papra/tree/main/packages/api-sdk).
diff --git a/packages/cli/bin/papra.mjs b/packages/cli/bin/papra.mjs
old mode 100644
new mode 100755
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 84184e41..69f92f36 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -27,6 +27,7 @@
"papra": "./bin/papra.mjs"
},
"files": [
+ "bin",
"dist"
],
"scripts": {
diff --git a/packages/cli/src/commands/documents/import/import.command.ts b/packages/cli/src/commands/documents/import/import.command.ts
index ebf097fe..ed8932a2 100644
--- a/packages/cli/src/commands/documents/import/import.command.ts
+++ b/packages/cli/src/commands/documents/import/import.command.ts
@@ -19,7 +19,6 @@ export const importCommand = defineCommand({
path: {
type: 'positional',
description: 'The path to the document to import',
- alias: 'p',
valueHint: './document.pdf',
},
organizationId: organizationIdArgument,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2b135353..2da17868 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -39,20 +39,20 @@ importers:
apps/docs:
dependencies:
'@astrojs/starlight':
- specifier: ^0.34.1
+ specifier: ^0.34.2
astro:
- specifier: ^5.7.5
+ specifier: ^5.7.10
sharp:
specifier: ^0.32.5
version: 0.32.6
starlight-links-validator:
specifier: ^0.16.0
starlight-theme-rapide:
specifier: ^0.5.0
zod-to-json-schema:
specifier: ^3.24.5
version: 3.24.5([email protected])
@@ -575,8 +575,8 @@ packages:
'@astrojs/[email protected]':
resolution: {integrity: sha512-nYE4lKQtk+Kbrw/w0G0TTgT724co0jUsU4tPlHY9au5HmTBKbwiCLwO/15b1/y13aZ4Kr9ZbMeMHlXuwn0ty4Q==}
- '@astrojs/[email protected]':
- resolution: {integrity: sha512-FmgS3R4SfLX8hmXoxNG5w1YicAs29Ix8A1cqczHEB4zJzIZVrvPiTEaQffJztqXTWERZtSZhHsckyDWImOPzJA==}
+ '@astrojs/[email protected]':
+ resolution: {integrity: sha512-/XwBXQ4ZyQBEETZIPw2pa+UsKawkpRVO7CF6QVpOmteGfUxCrsD3n26G0OsnWHh0Gfo67QkAqM0FsGmDuNUVHw==}
peerDependencies:
astro: ^5.5.0
@@ -2663,39 +2663,21 @@ packages:
'@selderee/[email protected]':
resolution: {integrity: sha512-P33hHGdldxGabLFjPPpaTxVolMrzrcegejx+0GxjrIb9Zv48D8yAIA/QTDR2dFl7Uz7urX8aX6+5bCZslr+gWQ==}
- '@shikijs/[email protected]':
- resolution: {integrity: sha512-FhsdxMWYu/C11sFisEp7FMGBtX/OSSbnXZDMBhGuUDBNTdsoZlMSgQv5f90rwvzWAdWIW6VobD+G3IrazxA6dQ==}
-
'@shikijs/[email protected]':
resolution: {integrity: sha512-CovkFL2WVaHk6PCrwv6ctlmD4SS1qtIfN8yEyDXDYWh4ONvomdM9MaFw20qHuqJOcb8/xrkqoWQRJ//X10phOQ==}
- '@shikijs/[email protected]':
- resolution: {integrity: sha512-eMdcUzN3FMQYxOmRf2rmU8frikzoSHbQDFH2hIuXsrMO+IBOCI9BeeRkCiBkcLDHeRKbOCtYMJK3D6U32ooU9Q==}
-
'@shikijs/[email protected]':
resolution: {integrity: sha512-XlhnFGv0glq7pfsoN0KyBCz9FJU678LZdQ2LqlIdAj6JKsg5xpYKay3DkazXWExp3DTJJK9rMOuGzU2911pg7Q==}
- '@shikijs/[email protected]':
- resolution: {integrity: sha512-wZZAkayEn6qu2+YjenEoFqj0OyQI64EWsNR6/71d1EkG4sxEOFooowKivsWPpaWNBu3sxAG+zPz5kzBL/SsreQ==}
-
'@shikijs/[email protected]':
resolution: {integrity: sha512-l0vIw+GxeNU7uGnsu6B+Crpeqf+WTQ2Va71cHb5ZYWEVEPdfYwY5kXwYqRJwHrxz9WH+pjSpXQz+TJgAsrkA5A==}
- '@shikijs/[email protected]':
- resolution: {integrity: sha512-If0iDHYRSGbihiA8+7uRsgb1er1Yj11pwpX1c6HLYnizDsKAw5iaT3JXj5ZpaimXSWky/IhxTm7C6nkiYVym+A==}
-
'@shikijs/[email protected]':
resolution: {integrity: sha512-zt6Kf/7XpBQKSI9eqku+arLkAcDQ3NHJO6zFjiChI8w0Oz6Jjjay7pToottjQGjSDCFk++R85643WbyINcuL+g==}
- '@shikijs/[email protected]':
- resolution: {integrity: sha512-k5DKJUT8IldBvAm8WcrDT5+7GA7se6lLksR+2E3SvyqGTyFMzU2F9Gb7rmD+t+Pga1MKrYFxDIeyWjMZWM6uBQ==}
-
'@shikijs/[email protected]':
resolution: {integrity: sha512-tXeCvLXBnqq34B0YZUEaAD1lD4lmN6TOHAhnHacj4Owh7Ptb/rf5XCDeROZt2rEOk5yuka3OOW2zLqClV7/SOg==}
- '@shikijs/[email protected]':
- resolution: {integrity: sha512-/NTWAk4KE2M8uac0RhOsIhYQf4pdU0OywQuYDGIGAJ6Mjunxl2cGiuLkvu4HLCMn+OTTLRWkjZITp+aYJv60yA==}
-
'@shikijs/[email protected]':
resolution: {integrity: sha512-KPCGnHG6k06QG/2pnYGbFtFvpVJmC3uIpXrAiPrawETifujPBv0Se2oUxm5qYgjCvGJS9InKvjytOdN+bGuX+Q==}
@@ -3723,8 +3705,8 @@ packages:
peerDependencies:
astro: ^4.0.0-beta || ^5.0.0-beta || ^3.3.0
- resolution: {integrity: sha512-c59YuYiXyWWnUMOBlDczrjqKzF0dJQP20EP9vqDggcyKm//tEt9iJHNwoYq4r3UeO9UJCwlGK8FwaGTAwwF3IA==}
+ resolution: {integrity: sha512-9TQcFZqP2w6//JXXUHfw8/5PX7KUx9EkG5O3m+hISuyeUztvjY1q5+p7+C5HiXyg24Zs3KkpieoL5BGRXGCAGA==}
engines: {node: ^18.17.1 || ^20.3.0 || >=22.0.0, npm: '>=9.6.5', pnpm: '>=7.1.0'}
hasBin: true
@@ -4457,9 +4439,6 @@ packages:
resolution: {integrity: sha512-CjVQyG7n7Sr+eBXE86HIulnL5N8xZY1sgmOPGuq/F0Rr0FJq63lg0kEtOIDfZBk44FnDLf6FUJ+dsJcuiUDdDQ==}
- resolution: {integrity: sha512-LRlerrMYoIDrT6jgpeZ2YYl/L8EulRTt5hQcYjy5AInh7HWXKimpqx68aknBFpGL2+/IcogTcaydJEgaTmOpDg==}
-
resolution: {integrity: sha512-EC+0oUMY1Rqm4O6LLrgjtYDvcVYTy7chDnM4Q7030tP4Kwj3u/pR6gP9ygnp2CJMK5Gq+9Q2oqmrFJAz01DXjw==}
@@ -5597,6 +5576,7 @@ packages:
resolution: {integrity: sha512-T9eIRCs6b0J1SHKYIvD8+KCJMcWZ900iZyxdnSCdqxN12Z1ijzT+jY5nrk72Jw4B0HGzms2NgpryArlJqvc3Lw==}
+ cpu: [x64, arm64, wasm32]
os: [darwin, linux, win32]
@@ -6144,12 +6124,6 @@ packages:
resolution: {integrity: sha512-fD9o5ebCmEAA9dLysajdQvuKzLL7cj+w7DQjuO3Cb6IwafENfx6iL+RGkmyW82pVRsvgzixsWinHvgxTMJvdIA==}
- resolution: {integrity: sha512-yNxcQ8sKvURiTwP0mV6bLQCYE7NKfKRRWunhbZnXgxSmB1OXa1lHrN3o4DZd+0Si0kU5blidK7BcROO8qv5TZA==}
-
- resolution: {integrity: sha512-SNwG909cSLo4vPyyPbU/VJkEc9WOXqu2ycBlfd1UCXLqk1IijcQktSBb2yRQ2UFPsDhpkaf+C1dtT3PkLK/yWA==}
-
resolution: {integrity: sha512-VtX1kepWO+7HG7IWV5v72JhiqofK7XsiHmtgnvurnNOTdIvE5mrdWYtsOrQyrXCv1L2Ckm08hywp+MFO7rC4Ug==}
@@ -6891,9 +6865,6 @@ packages:
resolution: {integrity: sha512-AzqKpGKjrj7EM6rKVQEPpB288oCfnrEIuyoT9cyF4nmGa7V8Zk6f7RRqYisX8X9m+Q7bd632aZW4ky7EhbQztA==}
engines: {node: '>= 0.4'}
- resolution: {integrity: sha512-VML/2o1/KGYkEf/stJJ+s9Ypn7jUKQPomGLGYso4JJFMFxVDyPNsjsI3MB3KLjlMOeH44gyaPdXC6rik2WXvUQ==}
-
resolution: {integrity: sha512-j0Z1tG5vlOFGW8JVj0Cpuatzvshes7VJy5ncDmmMaYcmnGW0Js1N81TOW98ivTFNZfKRn9uwEg/aIm638o368g==}
@@ -7357,8 +7328,8 @@ packages:
resolution: {integrity: sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==}
- resolution: {integrity: sha512-RoF14/tOhLvDa7R5K6A3PjsfJVFKvadvRpWjfV1ttabUe9704P1ie9z1ABLWEts/8SxrBVePav/XhgeFNltpsw==}
+ resolution: {integrity: sha512-zKSY9qO8svWYns+FGKjyVdLvpGPwqmsCjeJLN1xndMiqxHWBAhoWDMYMG960MxeV48clBmG+fDP59dHY1VoZvg==}
resolution: {integrity: sha512-amQa0Ep2m6hE2g72AugUItjbuM8X8cGQnFoHk0pGfrFeT9GZhzN5SW8nRsiGKK7Aif4CrACPENkA6P/Lw6fHGQ==}
@@ -7579,8 +7550,8 @@ packages:
terser:
optional: true
- resolution: {integrity: sha512-5nXH+QsELbFKhsEfWLkHrvgRpTdGJzqOZ+utSdmPTvwHmvU6ITTm3xx+mRusihkcI8GeC7lCDyn3kDtiki9scw==}
+ resolution: {integrity: sha512-BiReIiMS2fyFqbqNT/Qqt4CVITDU9M9vE+DKcVAsB+ZV0wvTKd+3hMbkpxz1b+NmEDMegpVbisKiAZOnvO92Sw==}
engines: {node: ^18.0.0 || ^20.0.0 || >=22.0.0}
hasBin: true
peerDependencies:
@@ -8079,7 +8050,7 @@ snapshots:
remark-parse: 11.0.0
remark-rehype: 11.1.2
remark-smartypants: 3.0.2
- shiki: 3.2.1
+ shiki: 3.3.0
smol-toml: 1.3.1
unified: 11.0.5
unist-util-remove-position: 5.0.0
@@ -8089,12 +8060,12 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
'@astrojs/markdown-remark': 6.3.1
'@mdx-js/mdx': 3.1.0([email protected])
acorn: 8.14.1
es-module-lexer: 1.6.0
estree-util-visit: 2.0.0
hast-util-to-html: 9.0.5
@@ -8118,17 +8089,17 @@ snapshots:
stream-replace-string: 2.0.0
zod: 3.24.2
dependencies:
'@astrojs/markdown-remark': 6.3.1
'@astrojs/sitemap': 3.3.0
'@pagefind/default-ui': 1.3.0
'@types/hast': 3.0.4
'@types/js-yaml': 4.0.9
'@types/mdast': 4.0.4
bcp-47: 2.1.0
hast-util-from-html: 2.0.3
hast-util-select: 6.0.4
@@ -8768,7 +8739,7 @@ snapshots:
dependencies:
- '@babel/types': 7.26.3
+ '@babel/types': 7.27.0
dependencies:
@@ -10188,13 +10159,6 @@ snapshots:
domhandler: 5.0.3
selderee: 0.11.0
- '@shikijs/[email protected]':
- dependencies:
- '@shikijs/types': 3.2.1
- '@shikijs/vscode-textmate': 10.0.2
- '@types/hast': 3.0.4
- hast-util-to-html: 9.0.5
-
'@shikijs/[email protected]':
dependencies:
'@shikijs/types': 3.3.0
@@ -10202,49 +10166,25 @@ snapshots:
'@types/hast': 3.0.4
hast-util-to-html: 9.0.5
- '@shikijs/[email protected]':
- dependencies:
- '@shikijs/types': 3.2.1
- '@shikijs/vscode-textmate': 10.0.2
- oniguruma-to-es: 4.1.0
-
'@shikijs/[email protected]':
dependencies:
'@shikijs/types': 3.3.0
'@shikijs/vscode-textmate': 10.0.2
oniguruma-to-es: 4.3.1
- '@shikijs/[email protected]':
- dependencies:
- '@shikijs/types': 3.2.1
- '@shikijs/vscode-textmate': 10.0.2
-
'@shikijs/[email protected]':
dependencies:
'@shikijs/types': 3.3.0
'@shikijs/vscode-textmate': 10.0.2
- '@shikijs/[email protected]':
- dependencies:
- '@shikijs/types': 3.2.1
-
'@shikijs/[email protected]':
dependencies:
'@shikijs/types': 3.3.0
- '@shikijs/[email protected]':
- dependencies:
- '@shikijs/types': 3.2.1
-
'@shikijs/[email protected]':
dependencies:
'@shikijs/types': 3.3.0
- '@shikijs/[email protected]':
- dependencies:
- '@shikijs/vscode-textmate': 10.0.2
- '@types/hast': 3.0.4
-
'@shikijs/[email protected]':
dependencies:
'@shikijs/vscode-textmate': 10.0.2
@@ -11570,12 +11510,12 @@ snapshots:
- supports-color
- typescript
dependencies:
rehype-expressive-code: 0.41.2
dependencies:
'@astrojs/compiler': 2.11.0
'@astrojs/internal-helpers': 0.6.1
@@ -11619,17 +11559,17 @@ snapshots:
prompts: 2.4.2
rehype: 13.0.2
semver: 7.7.1
- shiki: 3.2.1
+ shiki: 3.3.0
tinyexec: 0.3.2
- tinyglobby: 0.2.12
+ tinyglobby: 0.2.13
tsconfck: 3.1.5([email protected])
ultrahtml: 1.6.0
- unifont: 0.2.0
+ unifont: 0.4.1
unist-util-visit: 5.0.0
unstorage: 1.15.0(@azure/[email protected])([email protected])
vfile: 6.0.3
xxhash-wasm: 1.1.0
yargs-parser: 21.1.1
yocto-spinner: 0.2.1
@@ -12392,8 +12332,6 @@ snapshots:
-
@@ -14845,15 +14783,6 @@ snapshots:
-
- dependencies:
- emoji-regex-xs: 1.0.0
- oniguruma-parser: 0.5.4
- regex: 6.0.1
- regex-recursion: 6.0.2
-
dependencies:
oniguruma-parser: 0.12.0
@@ -15734,17 +15663,6 @@ snapshots:
- dependencies:
- '@shikijs/core': 3.2.1
- '@shikijs/engine-javascript': 3.2.1
- '@shikijs/engine-oniguruma': 3.2.1
- '@shikijs/langs': 3.2.1
- '@shikijs/themes': 3.2.1
- '@shikijs/types': 3.2.1
- '@shikijs/vscode-textmate': 10.0.2
- '@types/hast': 3.0.4
-
dependencies:
'@shikijs/core': 3.3.0
@@ -15898,9 +15816,9 @@ snapshots:
dependencies:
'@types/picomatch': 3.0.2
github-slugger: 2.0.0
hast-util-from-html: 2.0.3
@@ -15914,9 +15832,9 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
@@ -16280,7 +16198,7 @@ snapshots:
trough: 2.2.0
vfile: 6.0.3
dependencies:
css-tree: 3.1.0
ohash: 2.0.11
@@ -16511,7 +16429,7 @@ snapshots:
'@types/node': 22.15.3
fsevents: 2.3.3
dependencies:
esbuild: 0.25.2
fdir: 6.4.4([email protected])
@@ -16530,9 +16448,9 @@ snapshots:
optionalDependencies:
vite: 5.4.14(@types/[email protected])
optionalDependencies:
dependencies: