Upload a document from the Finder, on a Mac
Filing a document from a Mac means opening the browser, signing in, then finding the file again. This page adds a Send to PDF Archive entry to the Finder right click menu: the document goes from where it already is, with nothing to open.
The setup is done once, in about ten minutes. It goes through Terminal twice, and needs an upload token, which is part of a paid tier.
01Create an upload token
In your account, open the integrations page and create a token, ticking the Add permission. That one, and only that one, allows files to be uploaded: this token will be able neither to read nor to delete your documents.
Leave the scope on All my folders if you want to choose the destination at every upload. Limit it to one folder if this action must never write anywhere else.
The token is shown only once. Copy it before leaving the page; you will paste it at step 3.
02Install the client on the Mac
Open Terminal (the Applications folder, Utilities inside it), paste this line and press return. It downloads a small script, makes it executable and installs it.
The password it asks for is the one for your Mac session. Nothing else is installed: no application and no background service.
03Save the token on the Mac
Still in Terminal, open the settings file.
It opens in TextEdit. Paste your token between the quotation marks on the first line, save with Cmd+S, then close the window.
PDF_ARCHIVE_TOKEN="pdfa_PasteYourTokenHere" PDF_ARCHIVE_FOLDER="" PDF_ARCHIVE_ASK="1"
04Check that the connection works
This command asks PDF Archive for the list of your folders. If it prints them, the token is good and the rest will follow.
Note the number of the folder you will use most often as you go: it serves to force a destination, further down.
05Create the quick action
Open Automator (the Applications folder), choose New Document, then the Quick Action type.
Three settings, in the order of the window.
- At the top: the workflow receives files or folders in Finder.
- In the left column, under Utilities, drag Run Shell Script into the area on the right.
- In that action, set Shell to /bin/bash and, this is the point not to miss, Pass input to as arguments.
Then replace the content of the script with this line.
Save with Cmd+S, under the name that will appear in the right click menu, for example Send to PDF Archive.
/usr/local/bin/pdf-archive-finder "$@"
06Try it
In the Finder, right click a document, then Quick Actions and Send to PDF Archive. You can select several files at once.
Depending on the version of macOS, the entry sits under Services rather than under Quick Actions. If it appears nowhere, switch it on in System Settings, under Keyboard, the Keyboard Shortcuts button, the Services section, the Files and Folders group.
07Worth knowing
- Choosing the folder the documents land in
Three ways to answer the question, depending on whether you want to decide every time or never think about it again. The first two are set in the file from step 3.
Setting What happens on right click PDF_ARCHIVE_ASK="1" the defaultA list of your folders opens, with last time selected. The Cancel button ends the upload. PDF_ARCHIVE_ASK="0"
PDF_ARCHIVE_FOLDER="1097"No question, everything goes into that folder. The number is the one printed by pdf-archive-finder --folders. A token limited to one folder The destination is carried by the token, on the server. What the Mac asks or offers changes nothing, and a stolen token cannot write anywhere else. PDF ArchiveDestination folder:InvoicesContractsScanned postCancelSendThe question asked at every uploadLast time folder is already selected: for most uploads there is nothing to do but confirm. - Two separate entries in the right click menu
To have, say, Send to Invoices and Send to Contracts side by side, create two quick actions whose script forces the destination, each with its own folder number.
PDF_ARCHIVE_ASK=0 PDF_ARCHIVE_FOLDER=1130 /usr/local/bin/pdf-archive-finder "$@"The name you save the quick action under is the one that appears in the menu: name it after the folder.
- Knowing that the document actually arrived
The Mac only gives you back control once the server has answered. Three proofs stack up, from the most immediate to the most lasting.
Proof What it is worth The notification It names the document when there is only one, and counts them when there are several. Focus mode can hold it back: on its own it is therefore not enough. The link in the clipboard The link to the filed document is copied there automatically. It pastes into an email, and it opens the document page in your archive. This is the proof that depends on no setting of the Mac. The token log Every upload is recorded with its date, the name of the document and the IP address, in the activity table at the bottom of the tokens page. That is where you look afterwards, or when in doubt. A large document can take longer to process than to upload. The notification then says filing in progress instead of naming the document: it has been received and it will appear in the chosen folder, but its link is not available yet.
- If something goes wrong
A failure always opens a window, never a plain notification: a failed upload must not be able to pass unnoticed. The message is given file by file.
Message What to do No token configured Step 3 was not done, or the file was saved empty. Open it again with pdf-archive-finder --settings. Token missing, invalid or revoked The token was revoked, or pasted wrongly. Create a new one on the tokens page. This token does not allow files to be added The Add permission was not ticked at creation. It cannot be added afterwards: create a new token and revoke the old one. Invalid destination folder, or no folder chosen The folder was deleted, or the token is not limited to a folder and no destination was given. Read the numbers again with pdf-archive-finder --folders. This folder is read only It is a folder shared with you without upload rights. Choose a folder of your own. File too large for your plan This route accepts 200 MB per document. Above that, use the upload page in the portal. Not enough storage The account quota is reached. Nothing was written. Processing the document failed The file arrived but could not be processed, for instance because it is damaged. Open it on the Mac to check, then try again. No network, or server unreachable Nothing was sent. Try again once the connection is back. Nothing happens at all Notifications are probably switched off. Check the clipboard: if the link to the document is there, the upload did happen. To replace notifications with windows, add PDF_ARCHIVE_DIALOG="1" to the settings file. - What this version does not do
No description and no keywords at upload. Every document arrives with an automatic description carrying the date, and the keyword api. The rest is filled in from the document page.
Mac folders are not supported. A selection containing one is refused, naming the folder at fault. Select the files themselves.
The notification is not signed PDF Archive. macOS attributes it to the application running the script, so to Automator. That is the price of a setup with no application to install.
- On another system, or to go further
The client installed at step 2 is not limited to the Finder: it takes file paths as arguments, so it can be called from a script, a scheduled task or a watched folder just as well. The CLI, API and S3 page describes those three routes, on a Mac as much as on Linux and Windows.
The same token also connects your archive to an MCP capable AI assistant, which can then search your documents and file its own: see the AI integration.
- The token stays on your Mac, in clear text
It lives in your home folder, at ~/.config/pdf-archive/config, readable by your session. It is an upload credential: it gives access neither to your documents nor to your account, and it is revoked in one click from the tokens page. On a shared Mac, give it the scope of a single folder when you create it, before copying it into that file.