CLI guide

Prerequisites and sign-in

Requires .NET 10, the CLI package, and a NovelShaft account. Windows and Linux have been tested locally. The server must also be open to CLI connections.

After installation, run login and authorize NovelShaft CLI in the browser. Then use tools to verify the connection. status only checks the locally saved login; it does not contact the server.

novelshaft login
novelshaft tools

Review shared access scope and limits before connecting.

Find and call an operation

tools lists the operations available on the server. describe returns an operation's input schema; call executes it. Operation names are case-sensitive.

novelshaft tools --search GetProject --json
novelshaft describe GetProjects
novelshaft call GetProjects

For operations with arguments, prepare a JSON file using the path, query, and body fields shown by describe. Pass it with --input request.json, or use --input - to read from standard input. Call results go to stdout as JSON; diagnostics go to stderr.

Prepare an edit

novelshaft describe GetProjectHistoryState
novelshaft describe CreateProjectNovelNode
novelshaft id
novelshaft call CreateProjectNovelNode --input request.json

Before calling the edit, fetch the target work's history state. Save the work ID, required content, a new operationId from id, and the required expectedProjectHistoryVersion in request.json. Keep this file to identify or retry the same request.

You can also supply --project, --operation-id, and --history-version. Specifying the same field in both JSON and an option is an error. The CLI does not automatically retry writes or overwrite a conflicting version.

Transfer files

Use describe to check the target IDs and history version required by each operation, then save them in the input file.

novelshaft describe UploadProjectReferenceFile
novelshaft call UploadProjectReferenceFile --input upload-request.json --file notes.txt --content-type text/plain
novelshaft describe GetProjectReferenceFileRawContent
novelshaft call GetProjectReferenceFileRawContent --input download-request.json --download downloaded-notes.txt

--file reads the local file into body.file; do not specify body.file again in JSON. --download saves to the explicit destination and fails if that file already exists. File size limits are in the shared specification. Shared limits

Handle exit codes

confirmation_required means the action has not run. Open confirmationUrl yourself and review the action in the browser. Then query GetMcpActionRequest using the returned request ID. Do not treat code 3 as success or repeatedly issue the original action.

Manage login information

If the browser does not open, use login --no-browser and open the displayed URL on the same computer. Enter your password only in the sign-in page. Do not paste passwords, authorization codes, or tokens into the terminal.

Credentials are saved per server under the OS LocalApplicationData directory, in NovelShaft/cli. Windows encrypts them with the current user's DPAPI. Linux/macOS restrict file access to the owner (0700 directory, 0600 file) but do not encrypt the contents; avoid shared accounts or shared home directories.

Use logout to request token revocation and remove the local login. A nonzero exit code means revocation could not be confirmed. To revoke the app's permission itself, use Account settings. Revoke access

Ordinary commands do not open a sign-in screen automatically. Run login again if required. Commands sharing credentials are locked; if a command reports another is running, wait for it to finish. Use novelshaft help for option syntax.