Commands Reference¶

This page documents every ipto command grouped by resource. All commands support the global flags listed at the bottom of this page.

Auth Commands¶

`ipto login`¶

Authenticate with the IPTO API.

ipto login
ipto login --token <session_token>
ipto login --api-key <key>

Flag	Type	Description
`--token`	string	Authenticate with an existing session token.
`--api-key`	string	Authenticate with an API key (non-interactive).

Example

# Interactive (opens browser)
ipto login

# Non-interactive (CI / agents)
ipto login --api-key ipto_abc_your_key_here

`ipto logout`¶

Clear stored credentials for the current profile.

ipto logout

`ipto whoami`¶

Display the currently authenticated user, tenant, and role. Equivalent to GET /v1/me.

ipto whoami

Example

$ ipto whoami
User:   [email protected]
Tenant: Acme Corp (t_01JQ3N...)
Role:   admin

$ ipto whoami --output json
{
  "user_id": "u_01JQ3N...",
  "email": "[email protected]",
  "tenant_id": "t_01JQ3N...",
  "tenant_name": "Acme Corp",
  "role": "admin"
}

Dataset Commands¶

`ipto datasets create`¶

Create a new dataset.

ipto datasets create --name <name> [flags]

Flag	Type	Default	Description
`--name`	string	required	Human-readable dataset name.
`--description`	string	`""`	Short description of the dataset.
`--modality`	string	`document`	Data modality: `document`, `image`, `video`, `audio`, `mixed`.
`--monetization`	string	`open`	Monetization model: `open`, `premium`, `outcome_share`.
`--pricing`	string	`fixed`	Pricing strategy: `fixed`, `time_decay`, `demand_curve`.
`--visibility`	string	`private`	Visibility: `private`, `listed`, `restricted`.

Example

ipto datasets create \
  --name "financial-data" \
  --description "Quarterly earnings reports 2020-2024" \
  --modality document \
  --monetization premium \
  --pricing time_decay \
  --visibility listed

`ipto datasets list`¶

List all datasets in the current tenant.

ipto datasets list [--output json|table]

Example

$ ipto datasets list
 ID                  NAME              STATUS   OBJECTS
 d_01JQ3N…           financial-data    active   142
 d_01JR7K…           satellite-imgs    draft      0

`ipto datasets get`¶

Retrieve details for a single dataset.

ipto datasets get <dataset_id>

Example

ipto datasets get d_01JQ3N...

`ipto datasets update`¶

Update a dataset's metadata or status.

ipto datasets update <dataset_id> [flags]

Flag	Type	Description
`--name`	string	New dataset name.
`--status`	string	New status: `draft`, `ingesting`, `active`, `paused`.

Example

ipto datasets update d_01JQ3N... --status paused

`ipto datasets delete`¶

Permanently delete a dataset and all its objects.

ipto datasets delete <dataset_id> [--confirm]

Flag	Type	Description
`--confirm`	bool	Skip the interactive confirmation prompt.

Warning

This action is irreversible. All objects and index data in the dataset will be permanently removed.

Object Commands¶

`ipto objects upload`¶

Upload one or more files to a dataset. The CLI transparently handles the three-step presigned flow (request URL, PUT file, confirm).

# Single file
ipto objects upload <dataset_id> <file_path> [--content-type <mime>]

# Bulk upload (directory)
ipto objects upload <dataset_id> <directory/> [--recursive]

Flag	Type	Description
`--content-type`	string	Override the MIME type (auto-detected by default).
`--recursive`	bool	Recursively upload all files in subdirectories.

Example

# Upload a single PDF
ipto objects upload d_01JQ3N... ./report.pdf

# Upload an entire directory recursively
ipto objects upload d_01JQ3N... ./reports/ --recursive

`ipto objects list`¶

List all objects in a dataset.

ipto objects list <dataset_id> [--output json|table]

Example

$ ipto objects list d_01JQ3N...
 ID                  FILENAME         SIZE      STATUS
 o_01JQ4A…           report.pdf       2.1 MB    ready
 o_01JQ4B…           summary.docx     340 KB    ready

`ipto objects get`¶

Retrieve metadata for a single object.

ipto objects get <object_id>

`ipto objects download`¶

Download an object to the local filesystem. The CLI fetches a presigned URL and streams the file.

ipto objects download <object_id> [--output <path>]

Flag	Type	Description
`--output`	string	Local file path. Defaults to the original filename in the current directory.

Example

ipto objects download o_01JQ4A... --output ./downloads/report.pdf

`ipto objects delete`¶

Delete an object from a dataset.

ipto objects delete <object_id> [--confirm]

Flag	Type	Description
`--confirm`	bool	Skip the interactive confirmation prompt.

Search Commands¶

`ipto search`¶

Search across one or more datasets.

ipto search <query> [flags]

Flag	Type	Default	Description
`--datasets`	string	all	Comma-separated dataset IDs to scope the search.
`--mode`	string	`auto`	Search mode: `lexical`, `dense`, `hybrid`, `auto`.
`--limit`	int	`10`	Maximum number of results.
`--filter-mime`	string	all	Comma-separated MIME types to include (e.g., `application/pdf,text/plain`).
`--output`	string	auto	Output format: `json`, `table`.
`--stdin`	bool	`false`	Read the query from stdin instead of the positional argument.

Example: interactive

ipto search "quarterly earnings 2024" --datasets d_01JQ3N... --mode hybrid --limit 5

Example: agent-friendly (stdin)

echo "quarterly earnings 2024" | ipto search --stdin --output json

API Key Commands¶

`ipto keys create`¶

Create a new scoped API key.

ipto keys create --name <name> --scopes <scope1,scope2> [--access-mode all_available|allow_list]

Flag	Type	Default	Description
`--name`	string	required	Human-readable key name.
`--scopes`	string	required	Comma-separated scopes (e.g., `search,datasets.read`).
`--access-mode`	string	`all_available`	`all_available` or `allow_list`.

Example

ipto keys create --name "ci-pipeline" --scopes search,datasets.read --access-mode all_available

`ipto keys list`¶

List all API keys for the current tenant.

ipto keys list

`ipto keys revoke`¶

Revoke an API key. The key becomes unusable immediately.

ipto keys revoke <key_id> [--confirm]

Flag	Type	Description
`--confirm`	bool	Skip the interactive confirmation prompt.

`ipto keys grant`¶

Grant an API key access to a specific dataset (when the key uses allow_list access mode).

ipto keys grant <key_id> --dataset <dataset_id>

Flag	Type	Description
`--dataset`	string	Dataset ID to grant access to.

`ipto keys revoke-grant`¶

Remove a dataset grant from an API key.

ipto keys revoke-grant <key_id> --grant <grant_id>

Flag	Type	Description
`--grant`	string	Grant ID to revoke.

Admin Commands¶

`ipto admin review list`¶

List objects pending admin review.

ipto admin review list

`ipto admin review approve`¶

Approve a pending object.

ipto admin review approve <tenant_id> <object_id>

Example

ipto admin review approve t_01JQ3N... o_01JQ4A...

`ipto admin review reject`¶

Reject a pending object with a reason.

ipto admin review reject <tenant_id> <object_id> --reason <text>

Flag	Type	Description
`--reason`	string	Human-readable rejection reason (required).

Utility Commands¶

`ipto config show`¶

Print the current resolved configuration (merging file, environment variables, and flags).

ipto config show

`ipto config set`¶

Update a single configuration value in ~/.ipto/config.toml.

ipto config set <key> <value>

Example

ipto config set default_profile staging
ipto config set api_url https://staging-api.ipto.ai

`ipto completion`¶

Generate shell completion scripts.

ipto completion <shell>

Supported shells: bash, zsh, fish.

Global Flags¶

These flags are available on every command.

Flag	Type	Default	Description
`--profile <name>`	string	config default	Named profile to use from `~/.ipto/config.toml`.
`--output json\\|table\\|yaml`	string	auto	Output format. Defaults to `table` in a TTY, `json` otherwise.
`--api-key <key>`	string		Override the API key for this invocation.
`--api-url <url>`	string		Override the API base URL for this invocation.
`--quiet`	bool	`false`	Suppress all non-error output.
`--verbose`	bool	`false`	Enable verbose/debug logging.
`--no-color`	bool	`false`	Disable colored output.
`--version`	bool		Print the CLI version and exit.
`--help`	bool		Print help for the current command and exit.

Commands Reference¶

Auth Commands¶

ipto login¶

ipto logout¶

ipto whoami¶

Dataset Commands¶

ipto datasets create¶

ipto datasets list¶

ipto datasets get¶

ipto datasets update¶

ipto datasets delete¶

Object Commands¶

ipto objects upload¶

ipto objects list¶

ipto objects get¶

ipto objects download¶

ipto objects delete¶

Search Commands¶

ipto search¶

API Key Commands¶

ipto keys create¶

ipto keys list¶

ipto keys revoke¶

ipto keys grant¶

ipto keys revoke-grant¶

Admin Commands¶

ipto admin review list¶

ipto admin review approve¶

ipto admin review reject¶

Utility Commands¶

ipto config show¶

ipto config set¶

ipto completion¶

Global Flags¶

`ipto login`¶

`ipto logout`¶

`ipto whoami`¶

`ipto datasets create`¶

`ipto datasets list`¶

`ipto datasets get`¶

`ipto datasets update`¶

`ipto datasets delete`¶

`ipto objects upload`¶

`ipto objects list`¶

`ipto objects get`¶

`ipto objects download`¶

`ipto objects delete`¶

`ipto search`¶

`ipto keys create`¶

`ipto keys list`¶

`ipto keys revoke`¶

`ipto keys grant`¶

`ipto keys revoke-grant`¶

`ipto admin review list`¶

`ipto admin review approve`¶

`ipto admin review reject`¶

`ipto config show`¶

`ipto config set`¶

`ipto completion`¶