Skip to content

commands.md

Latest commit

 

History

History
434 lines (316 loc) · 13.3 KB

commands.md

File metadata and controls

434 lines (316 loc) · 13.3 KB
Raw

Command Reference

diskd commands follow this shape:

diskd [GLOBAL FLAGS] <command> [ARGS] [FLAGS]

Global flags must be placed before the subcommand.

Global Flags

Flag Description
--base-url <url> Override the API gateway base URL.
--json Print machine-readable JSON when supported.
--quiet, -q Reduce progress and status messages on stderr.
--config <path> Use a custom config file instead of $DISKD_HOME/config.yaml.
-p, --project <id> Override the current project for one command.
-w, --workspace <id> Reserved compatibility flag; workspace scope comes from the token.

Command Parameters

Command Positional args Command flags API/behavior Output notes
ls [path] default context root --recursive, --long, --show-hidden, --show-system paths/tools/ls Text is ls-like: type marker (<DIR>, <FILE>), size, indexing status, then copyable Drive name with display metadata in parentheses; --json preserves raw entries.
tree [path] default context root -L/--depth <n> (--deep alias), -a/--all, -d/--dirs-only, -f/--full-path, -s/--size, --show-system bounded paths/tools/ls calls when depth is set; recursive paths/tools/ls without depth ASCII tree over Drive entries; --json prints the collected listing.
glob <pattern> --path <dir>, --show-hidden, --show-system paths/tools/glob Matching path entries.
grep <query> [paths...] --limit <n>, --offset <n> paths/tools/grep Exact/BM25 search; omitted paths use context root.
vsearch <query> [paths...] --limit <n>, --top <n> alias, --offset <n> paths/tools/vsearch Semantic search; prefer file paths when possible.
cat <path> --version <n> drive/files/download-url plus byte download Raw bytes to stdout.
read <path> --limit/--parts-limit, --offset/--parts-offset paths/tools/read Structured parts plus pagination metadata.
stat <path> none paths/tools/inode-ls Path metadata.
biquery <question> [paths...] none paths/tools/bi-query Natural-language spreadsheet question, not SQL.
database (db) subcommand-specific create, insert, query, commit, rollback, metadata, drop, set-status, resolve-by-inode, resolve-with-settings drive/db/* Generic Drive DB working API with optional --db-type.
telegram-db subcommand-specific create, insert, query, commit, metadata, drop flags drive/telegram/* Telegram SQLite DB working API; query uses SQL against the named DB.
upload <local...> --dest <dir>, --recursive, --force upload start, PUT, commit Uploads files/folders.
mkdir <path> none drive/paths/create Creates folder.
rm <path> --recursive drive/paths/delete Deletes file/folder.
mv <src> <dst> none drive/paths/rename Move/rename.
cp <src> <dst> --force client download then upload Copy through local client.
sync <folder> --dest <dir>, --once, --interval-seconds <n> repeated upload passes One-way local-to-Drive.
login none --dev, --app-url, --token, --credentials-file browser login or token exchange Stores bearer token.
logout none none local credential delete Clears auth.
whoami none none local JWT decode Prints workspace/subject metadata.
set-context [project] --list, --root/--clear project REST list or local config write Selects local project path prefix.
get-context none none local config read Prints active context.
version none none local metadata Prints CLI version.
update none --force GitHub release update Replaces binary after checksum verification.
mcp serve none none embedded MCP stdio Prints agent config when run directly.

Auth and Meta

login

Open browser login:

diskd login
diskd login --dev

By default, diskd login opens https://app.iosya.com/oauth-apps. The --dev flag uses https://app.upgraide.dev/oauth-apps.

Store an existing token:

diskd login --token "$APIS_ACCESS_TOKEN"

Request a token with OAuth client credentials:

diskd login --credentials-file ./credentials.json

The client first requests gateway scopes used by Drive and project commands. If the issuer rejects those scopes, the CLI retries with the client's default scope set.

logout

diskd logout

Deletes the stored credential file.

whoami

diskd --json whoami

Decodes workspace and subject metadata from the current bearer token.

version

diskd version
diskd --json version

update

diskd update
diskd update --force

Checks the latest diskd-ai/diskd-cli GitHub release, downloads the matching platform archive and .sha256 file, verifies the checksum, and replaces the running binary. --force reinstalls the latest release even when the compiled version matches.

Most human-facing commands perform a short startup update check. If a newer release exists, diskd prints a yellow stderr notice:

diskd 0.1.5 is available; current is 0.1.4. Run `diskd update`.

Startup checks are skipped for --json, --quiet, and diskd mcp serve.

Project Context

set-context --list

diskd --json set-context --list

Calls GET /v1/platform/projects/api/projects and prints project id and name.

set-context <project>

diskd set-context "Project Name"
diskd set-context 01PROJECTID

Stores the selected project in config.yaml. The project may be matched by id or name.

set-context --root

diskd set-context --root

Clears project context and uses the workspace root.

get-context

diskd --json get-context

Prints the stored project context or the workspace root default.

Path Rules

With no project context:

docs/a.txt -> /docs/a.txt
/docs/a.txt -> /docs/a.txt

With project 01PROJECT:

docs/a.txt -> /Projects/01PROJECT/docs/a.txt
/docs/a.txt -> /Projects/01PROJECT/docs/a.txt

The CLI rejects . and .. path segments before making a network request.

Read and Query Commands

ls

diskd ls [path] [--recursive] [--long] [--show-hidden] [--show-system]

Calls paths/tools/ls.

Human text output is one row per entry:

<DIR>          0 -              reports (Reports)
<FILE>         5 indexed        a.txt (A Document)

The indexing column reads indexingStatus/indexing_status, or - when the backend omits it. The name column keeps the raw Drive name or final path segment so it can be copied into the next command. When displayName/display_name or metadata.displayName/metadata.display_name differs, the CLI appends it in parentheses. Use diskd --json ls to keep the backend response unchanged for scripts.

tree

diskd tree [path] [-L depth] [-a] [-d] [-f] [-s] [--show-system]

When depth is set, calls paths/tools/ls non-recursively per displayed directory level so -L 2 does not fetch the full subtree before rendering. Without depth, calls paths/tools/ls once with recursive=true. Useful system-tree style flags:

Flag Purpose
-L, --depth, --deep <n> Limit displayed depth below the root path.
-a, --all Include hidden Drive entries (show_hidden=true).
-d, --dirs-only Show directories only.
-f, --full-path Show full Drive paths instead of names plus display metadata.
-s, --size Show byte size beside each entry.
--show-system Include system entries.

Example:

docs
|-- <FILE>        5 a.txt (A Document)
`-- <DIR>        0 reports (Reports)
    `-- <FILE>       17 q1.pdf (Q1 Report)

Use diskd --json tree to print the listing collected for the tree renderer.

glob

diskd glob "**/*.pdf" --path docs

Calls paths/tools/glob.

grep

diskd --json grep "payment terms" docs contracts --limit 20 --offset 0

Calls paths/tools/grep. Omitted paths default to the current context root. --limit <n> and --offset <n> page matched documents.

--ignore-case and --files-with-matches are parsed but rejected because the current Drive grep contract has no matching fields.

vsearch

diskd --json vsearch "renewal clauses" docs/agreement.pdf --limit 5 --offset 0

Calls paths/tools/vsearch. --limit <n> (alias --top <n>) and --offset <n> page matched documents. Omitted paths default to the current context root.

cat

diskd cat docs/report.pdf > report.pdf

Calls drive/files/download-url, then downloads and streams the returned URL to stdout.

read

diskd --json read docs/report.pdf --limit 5 --offset 0

Calls paths/tools/read and returns structured indexed document parts. --limit/--offset are aliases for --parts-limit/--parts-offset.

stat

diskd --json stat docs/report.pdf

Calls paths/tools/inode-ls, the deployed path-based metadata surface.

biquery

diskd --json biquery "what is the total amount?" docs/table.csv
diskd --json biquery "total amount grouped by name" docs/table.csv

Calls paths/tools/bi-query for indexed CSV, TSV, XLS, and XLSX files. The query is a natural-language question; Drive generates and runs the SQL.

database / db

diskd --json database create generic-db \
  --schema '{"items":["CREATE TABLE messages (id INTEGER PRIMARY KEY, text TEXT)"]}'
diskd --json db insert generic-db messages --rows '[{"id":1,"text":"hello"}]'
diskd --json database query generic-db "SELECT id, text FROM messages LIMIT 20"
diskd --json database query generic-db "SELECT id FROM messages WHERE text = ?" --parameters '["hello"]'
diskd --json database commit generic-db
diskd --json database rollback generic-db
diskd --json database metadata generic-db
diskd --json database drop generic-db
diskd --json database set-status generic-db ready --error "optional diagnostic"
diskd --json database resolve-by-inode db_inode_value
diskd --json database resolve-with-settings db_inode_value --db-type telegram

Drive methods:

create                -> drive/db/create
insert                -> drive/db/insert
query                 -> drive/db/query
commit                -> drive/db/commit
rollback              -> drive/db/rollback
metadata              -> drive/db/metadata
drop                  -> drive/db/drop
set-status            -> drive/db/set-status
resolve-by-inode      -> drive/db/resolve-by-inode
resolve-with-settings -> drive/db/resolve-with-settings

All database operations that address a DB by name accept optional --db-type <database|mailbox|telegram|webarchive|session>. create --schema/ --schema-file must be a JSON object. insert --rows/--rows-file must be a JSON array of row objects. query --parameters/--parameters-file must be a JSON array for positional SQL parameters.

telegram-db

diskd --json telegram-db create team-chat \
  --schema '{"items":["CREATE TABLE messages (id INTEGER PRIMARY KEY, text TEXT)"]}'
diskd --json telegram-db insert team-chat messages --rows '[{"id":1,"text":"hello"}]'
diskd --json telegram-db query team-chat "SELECT id, text FROM messages LIMIT 20"
diskd --json telegram-db query team-chat "SELECT id FROM messages WHERE text = ?" --parameters '["hello"]'
diskd --json telegram-db commit team-chat
diskd --json telegram-db metadata team-chat
diskd --json telegram-db drop team-chat

Drive methods:

create   -> drive/telegram/create
insert   -> drive/telegram/insert
query    -> drive/telegram/query
commit   -> drive/telegram/commit
metadata -> drive/telegram/metadata
drop     -> drive/telegram/drop

Telegram DB names may be provided with or without .telegram; the Drive handler appends the extension. create --schema/--schema-file must be a JSON object with an items array of SQL statements. insert --rows/--rows-file must be a JSON array of row objects. query --parameters/--parameters-file must be a JSON array for positional SQL parameters.

Write and Manage Commands

upload

diskd upload ./file.txt --dest docs --force
diskd upload ./folder --dest docs --recursive --force

For each file, the CLI computes SHA-256, calls drive/upload/start, PUTs bytes to the returned upload URL, and calls drive/upload/commit.

mkdir

diskd mkdir docs

Calls drive/paths/create.

rm

diskd rm docs/file.txt
diskd rm docs --recursive

Calls drive/paths/delete.

mv

diskd mv docs/a.txt docs/b.txt

Calls drive/paths/rename.

cp

diskd cp docs/a.txt docs/copy.txt --force

Downloads the source file and uploads it to the destination.

sync

diskd sync ./local-folder --dest docs --once
diskd sync ./local-folder --dest docs --interval-seconds 5

sync is one-way local-to-Drive. With --once, it uploads the current tree and exits. Without --once, it repeats the upload pass on a polling interval.

MCP

diskd mcp serve

When run directly in a terminal, prints instructions for adding the server to an LLM agent. When launched by an MCP client over stdio, starts the embedded stdio MCP server. See mcp.md.