Workspace files

Listing, reading and deleting files is free and works at any balance. Upload them, one file or a whole folder, with nace upload --workspace; replace one with nace upload --on-conflict new_version to the same path. See List files in the API reference.

List workspace filesCopy Anchor Link

nace workspace-files --path-prefix reports/ --status stale
# files (1):
#   stale      2.1MB  reports/q3.pdf  <file_id>

Stdout gets files (<total>):, the number of files that match, then one line per file, indented two spaces: its ingestion_status, its size right-aligned in 9 characters, its path and its id. When more pages follow, the last line is next: <cursor>: pass it as --cursor.

When the workspace's access labels kept files from you, stderr says how many.

Read a workspace fileCopy Anchor Link

nace workspace-file <file_id>              # the file, with its download and preview links
nace workspace-file <file_id> --metadata   # what ingestion learned about it
nace workspace-file <file_id> --versions   # every version, newest first

nace workspace-file FILE_ID prints the file as JSON, with download_url and preview_url, links to its bytes that work without your API key for 15 minutes. FILE_ID can also be a ws:<workspace_id>/<file_id> source, as nace upload --workspace ID prints it; that names the workspace too, and a different --workspace exits 2. A file uploaded without --workspace is only a source for the tools: nace workspace-file exits 1 with 404 workspace_not_found for it. The output is JSON with or without --json.

Delete a workspace fileCopy Anchor Link

nace workspace-file-delete <file_id>
# succeeded file_delete <job_id>

nace workspace-file-delete FILE_ID removes the file, what ingestion built from it, and cancels ingestions still running on it. It can't be undone. It waits for the file_delete job and prints its line, <status> file_delete <job_id>. FILE_ID can be a ws: source from nace upload --workspace ID, as for nace workspace-file.

Ingest filesCopy Anchor Link

nace ingest --path-prefix reports/ --stale-only
# ingested 2 | skipped 1 | failed 1 | 412 units
#   ingested  reports/q3.pdf
#   ingested  reports/q4.pdf
#   skipped_unchanged  reports/q2.pdf
#   failed  reports/bad.pdf Can't read it.
nace ingest --file-id <file_id> --file-id <file_id> --async

Ingestion reads your files and builds what search needs; it's the only command that makes files searchable. Upload a batch, then ingest it in one run, or let nace upload --ingest do both. Pricing is to be announced. See Ingest files.

What it prints. nace ingest starts an ingestion job, waits for it, and prints:

1. A summary: ingested <n> | skipped <n> | failed <n> | <n> units, with | empty <n> after skipped when some files had no rows.
2. A line per file: two spaces, its status (ingested, skipped_unchanged, skipped_empty or failed), two spaces, its path, and for a failed file a space and the error.

With --json, it prints the whole job instead, every file's outcome included.

When a file fails. A batch with successful files can still have a successful job when another file fails, but the command fails:

• Stderr lists each failed file as failed <path>: <error>.
• Then stderr ends with error: <n> of <m> files failed to ingest, counting the files ingested, skipped and failed, and the command exits 1, with --json too.
• Files that were only skipped exit 0.
• nace job applies the same rule to an ingestion it reads.

If every file fails, the job itself is failed and the command exits 1. With --json, inspect the job's error and its detail.failures for the affected paths; there is no successful result's outcomes list. A malformed PDF, for example, can produce parse_failed. Wait for the job and check its status and per-file errors before treating ingestion as complete.