Cue CLI tool

The CLI tool lets you sync a local folder to Cue or compare a local folder's content to that on Cue.

Use

Pre-steps

You need an API key in order to authenticate with the CLI tool.

• Go to your profile page and create an API key.
• Save the value in the environment variable CUE_API_KEY on your system*

• You can also specify it using the --key flag but it is more convenient and safe to use an environment variable.

File storage goes through Cue's gateway. CUE_STORAGE_DRIVER=firebase reaches Firebase Storage directly instead, which only still works against the emulator. Every command that reads or writes files follows it.

What commands?

• Run npx @qaecy/cue-cli --help to list all supported commands.
• Use the --help flag on any command to see all supported flags on that command (eg. npx @qaecy/cue-cli sync --help)

Sync a folder

To sync the current dir to the space with id <space-id> under the provider id d_drive (provider id is used to distinguish different document sources and if none is provided the default provider is used). The v-flag is for verbose logging so we can follow the progress.

npx @qaecy/cue-cli sync -s <space-id> -p . --provider d_drive -v

Preview a sync without changing anything

Use --dry-run to see what a sync would do before running it: the local/remote diff (new files, files that only need a file-location graph entry, remote files missing locally), and the credit cost — without uploading any file content or writing any metadata. Combine with -v to list the individual files in each category.

npx @qaecy/cue-cli sync -s <space-id> -p . --provider d_drive --dry-run -v

Sync part of a folder, without questions

--include, --exclude and --modified-after pick files by their path inside the folder. --json prints the dry run (or the sync's result) as one JSON object, and --yes skips the confirmation, which is how an agent runs it (the cue-upload skill): a dry run first, shown to the user, then the sync once they agree.

npx @qaecy/cue-cli sync --project-id <project-id> -p ~/NEST --include "*.pdf" "*.dwg" --exclude Arkiv --dry-run --json

npx @qaecy/cue-cli sync --project-id <project-id> -p ~/NEST --include "*.pdf" "*.dwg" --exclude Arkiv --yes --json

Sync command options

| Option | Description | Default | |-----------------------|------------------------------------------------------------------------------------------------------|--------------| | -s, --space <id> | Specify the space ID (omit to pick interactively) | N/A | | --project-id <id> | The project to sync to; the same as --space | N/A | | -p, --path <id> | Specify the folder path to sync (required) | N/A | | -k, --key <api-key> | Specify the API key (or set CUE_API_KEY env variable) | N/A | | --provider <id> | Specify the provider ID (e.g., sharepoint, drive, dropbox). Leave empty for default provider | "" | | -v, --verbose | Enable verbose output | false | | -e, --emulators | Use emulators for sync | false | | -z, --zip | Include zipped content. Will be unzipped to <zip_path>_unzipped. Max uncompressed size: 500 MB, max recursion depth: 3. Cleans up unzipped files after sync. | false | | --legacy | Write RDF metadata as serialised Turtle BLOBs to the processed storage bucket instead of patching the knowledge graph directly. Use this when the ledger and graph services are not yet available for the target environment. | false | | --metadata-only | Push filesystem-structure metadata for every local file directly to the commands API, without checking what is already on the remote, running a credit estimate, or uploading any file content. Useful for repairing missing graph metadata after a migration or interrupted sync. Can be combined with --legacy to write the metadata as BLOBs. | false | | --include <pattern...> | Only files whose path inside the folder matches. * stays within a folder, ** crosses folders, ? is one character; a pattern without / matches any file or folder name. Case-insensitive. | all files | | --exclude <pattern...> | Leave out files whose path matches, e.g. Arkiv, **/old/**, ~$* | none | | --modified-after <date> | Only files changed on or after this date, e.g. 2026-09-01 | N/A | | -y, --yes | Sync without asking to confirm | false | | --json | Print the dry run, or the result of the sync, as JSON on stdout (progress goes to stderr). Needs --project-id. | false | | --dry-run | Log the local/remote sync diff (new files, files only missing a file-location graph entry, remote files missing locally) and the credit cost, then exit. No file content is uploaded and no metadata is written — pending metadata from a previous interrupted sync is not flushed either. Combine with -v to list individual files per category. | false |

app-builder-tools

A set of JSON-output commands designed for agent-assisted Cue app development. All sub-commands accept -k/--key (or CUE_API_KEY), -e/--emulators, and -v/--verbose.

list-projects

List all projects accessible to the authenticated user.

npx @qaecy/cue-cli app-builder-tools list-projects

Outputs a JSON array with id, name, organizationID, isPublic, graphType, and lastSync for each project.

entity-summary-graph

Fetch the entity category relationship summary graph for a project — useful for understanding the knowledge graph schema before writing queries.

npx @qaecy/cue-cli app-builder-tools entity-summary-graph -s <project-id>

| Option | Description | Default | |----------------------|----------------------------------------------------------------------------------------------|---------| | -s, --space <id> | Project ID (required) | N/A | | -f, --format <fmt> | Output format: md (aligned text table), graph (JSON nodes + weighted edges), json (raw SPARQL result) | md | | --entity <iri> | Filter to the one-hop neighbourhood of this category IRI (prefixed, e.g. qcy-e:Building, or full URL) | N/A |

sparql

Execute a SPARQL SELECT query against a project triplestore. The query can be passed inline or piped via stdin. Outputs raw SPARQL JSON results.

npx @qaecy/cue-cli app-builder-tools sparql -s <project-id> -q "SELECT * WHERE { ?s ?p ?o } LIMIT 10"

echo "SELECT * WHERE { ?s ?p ?o } LIMIT 10" | npx @qaecy/cue-cli app-builder-tools sparql -s <project-id>

| Option | Description | Default | |---------------------|-----------------------------------------------------------|---------| | -s, --space <id> | Project ID (required) | N/A | | -q, --query <sparql> | SPARQL query string (or pipe query via stdin) | N/A |

The Cue MCP tools: projects, index, skills

Every tool of the Cue MCP server is also a command, with one flag per parameter. A toolkit is a command group, and a toolkit's own listing tool is a command of its own. cue-cli <group> --help lists a group's tools, and cue-cli <group> <tool> --help lists a tool's flags, with the descriptions the server gives an agent.

npx @qaecy/cue-cli projects list

npx @qaecy/cue-cli index schema -p <project-id> --mode overview

npx @qaecy/cue-cli index search -p <project-id> --input "fire doors" --limit 5

npx @qaecy/cue-cli index inspect -p <project-id> --ctx <ctx-id> --details high

npx @qaecy/cue-cli projects get -p <project-id> --format json

npx @qaecy/cue-cli projects update -p <project-id> --schema @schema.json --base-revision 7

npx @qaecy/cue-cli skills --name cue-retrieve

• -p, --project-id is the project, as projects list lists it.
• A list takes JSON ('["a","b"]') or a comma list (a,b). An object takes JSON.
• Any value starting with @ is read from that file.
• Every command also takes -k, -e, -v and --json, as below.

The commands are built from src/mcp-tools.json, which is generated from the server with nx run databases-cue:mcp-manifest. A databases-cue test fails when it is out of date. Tools that render a view (index_display, display_*) are left out: they belong in a chat.

apps, schema suggest, data-sources and code-lists

Commands that work on your computer rather than through the MCP server:

npx @qaecy/cue-cli apps save -p <project-id> --dir apps/organisations --name Organisations --icon users saves the app in a folder (index.html, app.js, app.css) as a draft in your apps, and prints it as JSON. Pass --app-id to revise a draft.

npx @qaecy/cue-cli apps publish -p <project-id> --app-id <app-id> saves a draft to your apps; --share also shares it with everyone on the project.

npx @qaecy/cue-cli schema suggest -p <project-id> --files drawing.pdf photo.jpg --intent "who reviewed each drawing" --out proposal.json proposes an extraction schema from sample files (the first pages of PDFs are rendered as images) and what you want captured. Nothing is stored, and the samples never become documents. --current proposal.json builds on an earlier proposal.

npx @qaecy/cue-cli data-sources inspect --file rooms.csv reads a spreadsheet (.csv, .xlsx, .xls, the first sheet with its headings in the first row) on your computer and prints, per column, how many rows fill it, how many values it has and a few of them. data-sources preview -p <project-id> --file rooms.csv --mapping mapping.json runs a sheet mapping over it without storing anything, and data-sources create ... --name "Room list" --yes stores the file as a new data source's own and writes its entities and relations to the graph. In the mapping an entity column may name its category by its schema key ({"kind": "entity", "category": "Room"}) and a relation its predicate by name ({"sourceColumn": "Site", "targetColumn": "Building", "predicate": "contains"}); both are looked up in the project's schema. data-sources list -p <project-id> lists the project's data sources.

npx @qaecy/cue-cli code-lists store -p <project-id> --file list.xlsx stores a code list (a document-class list, a cost-code plan) in the project as it is, never processed, under cue_code_lists/, and prints the file handle the server reads it by: index code-list --file <handle> reads its classes and flag columns and measures how the project's records write its codes, and index preview --code-list @plan.json carries it into a change set.

Signing in

Commands sign in with --key or CUE_API_KEY. Inside the Cue desktop app, cue-cli is on the agent's PATH and signs in as the app's user (CUE_SESSION_FILE), with no key. There the app's session wins over a CUE_API_KEY the shell profile exports; only --key overrides it.

mcp

Call any Cue MCP tool by name with its parameters as JSON, e.g. a tool newer than this CLI. The tool's markdown snippet is rendered to the terminal — headings, lists, tables, inline code and blockquotes — inside a titled box wrapped to the terminal width; pass --json for the raw result instead.

npx @qaecy/cue-cli mcp index_schema -s <project-id> -a '{"mode":"overview"}'

npx @qaecy/cue-cli mcp index_search -s <project-id> -a '{"input":"concrete"}'

The first argument is the tool name; --args carries that tool's parameters as a JSON object. --space is a convenience that fills project_id when it isn't already present in --args.

Options

| Option | Description | Default | |-----------------------|------------------------------------------------------------------------------------------------------|---------| | <tool> | Tool name (positional, required), e.g. index_search or projects_get | N/A | | -s, --space <id> | Project ID (merged into the call as project_id when not present in --args) | N/A | | -a, --args <json> | Tool arguments as a JSON object | {} | | -k, --key <api-key> | Specify the API key (or set CUE_API_KEY env variable) | N/A | | -e, --emulators | Use emulators | false | | -v, --verbose | Enable verbose output | false | | --json | Print the raw JSON result instead of the rendered Context | false |

util-remove-rdf-star

Remove RDF-star (quoted triple) statements from an NQuads file. Supports both plain .nq and gzipped .nq.gz files. If the input is gzipped the output will also be gzipped.

npx @qaecy/cue-cli util-remove-rdf-star -i <input.nq.gz> -o <output.nq.gz> -v

Options

| Option | Description | Default | |----------------------|-----------------------------------------|---------| | -i, --input <path> | Input file path (.nq or .nq.gz) (required) | N/A | | -o, --output <path>| Output file path (.nq or .nq.gz) (required) | N/A | | -v, --verbose | Enable verbose output | false |