Commands

Every command accepts the global flags --json, --workspace, and --token. Run graphon <group> --help for the full flag list.

Account

graphon whoami
graphon workspaces list
graphon workspaces use <workspaceId>

Members

graphon members list --query "alex"
graphon members update <memberId> --role editor
graphon members remove <memberId>

Invitations

graphon invitations create --role editor --email person@acme.dev
graphon invitations list
graphon invitations revoke <invitationId>

API keys

One API key works on the Graphon API, the storage API, and S3 tools. --owner workspace makes a workspace API key, which only Admins can manage. Without --role, a personal key gets your role and a workspace key gets viewer. create prints the key once, on stdout.

graphon api-keys create --name "Local CLI"
graphon api-keys create --name "ci" --owner workspace --role editor
graphon api-keys list
graphon api-keys list --owner workspace
graphon api-keys update <keyId> --role viewer
graphon api-keys revoke <keyId>

Webhooks

Graphon sends workspace events to a webhook URL as signed POSTs. A member makes a personal webhook by default. A workspace API key makes a workspace webhook. --owner workspace from a member needs an Admin. create and rotate-secret print the signing secret once, on stdout. --write-env <path> writes it to that env file as GRAPHON_WEBHOOK_SECRET instead. update takes --all-event-types and --all-buckets to remove a filter. See Receive events with webhooks.

graphon webhooks create --name indexing-callbacks \
  --url https://hooks.example.com/graphon \
  --event-type object.indexed --event-type object.indexing_failed \
  --write-env .env
graphon webhooks list
graphon webhooks get <webhookId>
graphon webhooks update <webhookId> --bucket <bucketId>
graphon webhooks update <webhookId> --disable
graphon webhooks test <webhookId>
graphon webhooks rotate-secret <webhookId> --write-env .env
graphon webhooks deliveries <webhookId> --status failed
graphon webhooks delivery <webhookId> <eventId>
graphon webhooks replay <webhookId> --since 2026-10-13T00:00:00Z --only-failed
graphon webhooks delete <webhookId>

S3 credentials

s3-credentials splits the API key in GRAPHON_API_KEY or --token into S3 credentials. It makes no network call. The default format prints shell exports. --format process prints JSON for an AWS credential_process profile. The command needs an API key. A login is not enough.

export GRAPHON_API_KEY="gak_..."
eval "$(graphon s3-credentials)"
graphon s3-credentials --format process

Buckets

buckets create needs a name alone. Bucket type, provider, and location are fixed when the bucket is created. In a terminal the command asks for the ones that no flag answers, and Enter takes the value it shows. Everywhere else, and with --json, the command uses gcp and the US multi-region and names them in its output. buckets locations lists every provider and location. graphon config set bucket.provider and bucket.location store a choice, and the command stops asking. The default provider and location can change in a later release, so a script that depends on one must pass the flag.

buckets index-status shows the indexing counts of a bucket and the files that are not indexed yet, in the order the index takes them. Add --filter failed to list the files that failed, or --watch to print again every 5 seconds until every file is finished.

graphon buckets create support-tickets
graphon buckets create support-tickets \
  --provider gcp --location us-central1 --indexing enabled
graphon buckets locations
graphon config set bucket.provider gcp
graphon config set bucket.location US
graphon buckets list
graphon buckets get support-tickets
graphon buckets usage support-tickets
graphon buckets index-status support-tickets --watch
graphon buckets delete support-tickets --confirm-name support-tickets

Objects

objects put switches to a multipart upload automatically for files over 64 MiB. It sends 16 MiB parts, 4 at a time, and retries a failed part. objects sync uploads a folder. It skips a file whose object has the same size and is newer, so a second run uploads only new and changed files. It never deletes an object. It stops at the first upload that Graphon refuses, and it does not follow symbolic links.

graphon objects put support-tickets incidents/timeout.json --file ./timeout.json
graphon objects list support-tickets --prefix incidents/
graphon objects get support-tickets incidents/timeout.json --output ./timeout.json
graphon objects sync support-tickets --dir ./incidents --prefix incidents/ --dry-run
graphon objects sync support-tickets --dir ./incidents --prefix incidents/
graphon objects delete support-tickets incidents/timeout.json

objects sync --from s3://<bucket>/<prefix> copies from a bucket at another S3 provider instead of a folder, with the same skip rule. It reads the source keys only from AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and, for temporary keys, AWS_SESSION_TOKEN. For a bucket outside Amazon S3, set --from-endpoint to the provider's S3 URL. Each object streams through your machine with no temporary file, and keeps its content type. The first line counts the source objects and bytes, so a --dry-run is also an inventory. Sync stops at the first read that the source refuses.

# Keys of the source bucket, never flags
export AWS_ACCESS_KEY_ID=<source access key ID>
export AWS_SECRET_ACCESS_KEY=<source secret access key>

# Amazon S3. Set AWS_REGION when the bucket is not in us-east-1.
graphon objects sync support-tickets --from s3://old-tickets/incidents --prefix incidents/ --dry-run

# Cloudflare R2, Google Cloud Storage with HMAC keys, or MinIO
graphon objects sync support-tickets --from s3://old-tickets/incidents \
  --from-endpoint https://storage.googleapis.com --prefix incidents/

Datasets

A dataset is a read-only set of documents that Graphon curates. Every workspace can query a published dataset. datasets list prints the id, the title, and the price of each one, and reads every page. datasets get takes an id or a slug. Pass the dataset id where a query command takes a bucket name. A paid dataset that your workspace has no access to shows locked. See Query a dataset.

graphon datasets list
graphon datasets list --category legal
graphon datasets get us-case-law
graphon search dstC4s3L4w0x1 "qualified immunity excessive force"
graphon ask dstC4s3L4w0x1 "Which cases overruled Chevron?"

Search, ask, chat, and research

The first argument of these commands is a bucket name, or a dataset id from graphon datasets list. A bucket must have indexing enabled. search prints the rank, the key, the version, the score, and each span that matched, such as chars 18240-19310 (pages 4-5), and prints a --cursor value for the next page. A span runs from its start to its end, without the end itself. Pages count from 1. read-spans prints the content of up to 50 spans, each under a line with its key and its span. Name one span with the key, --version-id, --unit, --start, and --end, or send a file with --spans: a JSON array of spans, or the next field of an earlier read. By default it prints the text, or the speech as lines with times. --include raw adds the span cut from the object, and --include object the whole object: add --delivery url to print a link to each. When a span is too large for one read, save the next field of the --json output and send it with --spans. ask prints one answer and the sources it cites. Each [[SRC:0001]] marker in the answer matches the source line with the same marker. chat answers one question for each line of input and sends the earlier turns with each one, so a follow-up can say "it"; a terminal gets a prompt, and piped input does not. research start returns a run id at once; add --watch to print each step until the answer arrives, or read the run later with research get. A research run stays readable until its expiresAt, seven days past the end. ask and chat store nothing, so there is no answer to read later. research start and ask --image are premium.

graphon search support-tickets "ERR_POOL_TIMEOUT" --mode keyword --limit 20
graphon search support-tickets "connection pool" --result-type passage
graphon read-spans support-tickets manuals/pump.pdf --version-id <versionId> --unit chars --start 1200 --end 3400
graphon read-spans support-tickets --spans spans.json --include text raw --delivery url
graphon ask support-tickets "Why did checkout stall?"
graphon chat support-tickets
graphon research start support-tickets "Every checkout timeout" --watch
graphon research get <researchId>

Jobs

Check the status of a background job, such as a bucket empty.

graphon jobs get <jobId>

Install

Manage the install of graphon itself.

graphon update          # update now
graphon doctor          # version, install path, and auto-update state
graphon uninstall       # remove graphon (--purge also removes logins)
graphon licenses        # licenses of the code that graphon ships