iA Writer supports a variety of commands to open, create, read, and write files.
Summary
Overview
Commands can be set to iA Writer by constructing special URLs:
ia-writer://command?parameter1=value1¶meter2=value2
x-callback-url
All commands can support x-callback-url:
ia-writer://x-callback-url/command?x-parameter1=x-value1¶meter1=value1¶meter2=value2
Some commands will return parameters on x-success
.
Auth
For privacy and security, commands that modify or return data using x-callback-url require auth-token
parameter. Auth token is synced across all your devices using iCloud. Auth token can be found in:
- On Mac: iA Writer → Preferences → General → URL Commands → Manage.
- On iOS: Library → Settings → URL Commands.
Data Types
- String
- Percent encoded. 4,000 or fewer characters before encoding.
- Library Path
- Percent encoded.
/File.txt
refers to a file in the default location (iCloud or local).Ideas: File.txt
refers to a file in the custom library location named Ideas.From Other Apps: File.txt
is available on iOS.- Use contextual menu in Library and Organizer to copy paths.
- Boolean
- Either
true
orfalse
.
Interface Commands
Open a screen in iA Writer.
open
command
Opens Editor with an existing document if found, or a new empty document.
Parameters
path
- Library Path. Required.
edit
- Boolean. Optional. Supported only on iOS and iPadOS.
false
by default. Iftrue
, keyboard will be shown. new-window
- Boolean. Optional. Supported only on macOS.
false
by default. Iftrue
, will open the document in a new window.
Return parameters on x-success
None.
new
command
Opens Editor with a new document.
Parameters
path
- Library Path. Optional. Path for the file to be created. If omitted the file will be created at the root of the default location. If the path points to a directory, the file will be automatically named. If the path points to a file, it must have a plain text file extension, or the path will be ignored. The proposed filename will be used, but adjusted to avoid overwriting an existing file.
text
- String. Optional. File contents.
edit
- Boolean. Optional. Supported only on iOS and iPadOS.
false
by default. Iftrue
, keyboard will be shown. new-window
- Boolean. Optional. Supported only on macOS.
false
by default. Iftrue
, will open the document in a new window.
Return parameters on x-success
None.
quick-search
command
Opens Quick Search with a given query.
Parameters
query
- String. Optional.
Return parameters on x-success
None.
Data Commands
Silenty read and write data.
read
command
Reads and returns files contents.
Parameters
auth-token
- String. Required.
path
- Library Path. Required. Path to the file to read.
Return parameters on x-success
path
- Library Path. Path to the file.
text
- String. File text.
write
command
Creates or modifies an existing file and returns file contents.
Parameters
auth-token
- String. Required.
path
- Library Path. Required.
text
- String. Optional.
mode
- String. Optional.
create
Default. Adjusts last path component to avoid replacing an existing file.replace
Replaces an existing file.append
Appends the given text to an existing file; creates a file if it doesn’t exist.append-location
- String. Optional. Used only when
mode
isappend
. beginning
Append text at the beginning of a file.end
Default. Append text at the end of a file.append-padding
- Boolean. Optional. Default:
true
. Make a paragraph out of appended text. Used only whenmode
isappend
.
Return parameters on x-success
path
- Library Path. Path to the file that was created or modified.
text
- String. File contents after writing.
version
command
Returns iA Writer app version and URL scheme version.
Parameters
None.
Return parameters on x-success
scheme-version
- String. URL scheme version.
app-version
- String. App version.
Version History
- 1
- Initial release.
- 2
- Fixed
write
command parameterappend-padding
. It was inverted in version 1: padding was appended withfalse
, and not appended withtrue
. - 3
- Changed
write
command withmode=append
to create a file if it doesn’t exist. - 4
- Added
open
andnew
command parameternew-window
. - Changed
open
command to open a new empty file if file atpath
is not found. - Changed
write
command to create target folder if it doesn’t exist. - Renamed Path data type to Library Path, and updated the data type format. Old format is deprecated.