fastio
A command-line interface for the Fastio cloud storage platform. Built in Rust for speed, reliability, and cross-platform support.
Installation
npm (recommended)
npm install -g @vividengine/fastio-cli
Or run without installing:
npx @vividengine/fastio-cli --help
Shell script
curl -fsSL https://raw.githubusercontent.com/VEngTech/fastio_cli/main/install.sh | sh
Binary download
Pre-built binaries for macOS, Linux, and Windows are available on the Releases page.
From source
Requires Rust 1.88+ (edition 2024):
cargo install --path .
Quick Start
# Log in (opens browser for secure authentication)
fastio auth login
# Check auth status
fastio auth status
# List organizations
fastio org list
# Create a workspace
fastio workspace create --org <org_id> "My Workspace"
# Upload a file
fastio upload file --workspace <workspace_id> ./document.pdf
# Download a file
fastio download file --workspace <workspace_id> <node_id> --output ./downloads/
# Ask the AI about your workspace
fastio ai chat --workspace <workspace_id> "What files do I have?"
# Log out
fastio auth logout
Authentication
The CLI supports multiple authentication methods, checked in this order:
--tokenflag (one-off bearer token)FASTIO_TOKENenvironment variableFASTIO_API_KEYenvironment variable- Stored credentials from
--profile(or default profile)
Browser Login (Recommended)
fastio auth login
# Request an admin (`rwa`) access mode, or a read-only one
fastio auth login --admin
fastio auth login --read-only
# Also request permission to change account settings (`userdetails:*:rw`)
fastio auth login --account-settings
auth login opens your browser to Fastio's sign-in page (including 2FA, if enabled on your account)
and receives the result on a short-lived local callback. Tokens are stored locally and automatically
refreshed.
--admin and --read-only request a ceiling, not a role: the consent page may grant less than you asked for. Run fastio auth scopes afterwards for the live view of what the credential may do — fastio auth status only shows the scopes cached when the profile signed in.
No browser on this machine? Use --no-browser:
fastio auth login --no-browser
This prints the sign-in URL instead of opening it. Open it on any device, sign in, and paste the code it displays back into the CLI prompt.
Password sign-in from the CLI has been removed — it's handled on the browser sign-in page above. For unattended or CI use, create an API key instead (below).
API Key
# Create an API key
fastio auth api-key create --name "CI pipeline"
# Create one scoped to a single organization, with admin access
fastio auth api-key create --name "release bot" --org 1234567890123456789 --admin
# Use it for subsequent commands
export FASTIO_API_KEY=your-key-here
fastio org list
Scopes are entity_type:entity_id:access_mode strings, where the access mode is r, rw, or rwa (admin). --org / --workspace / --share (repeatable) and --all select the entities, --admin / --read-only set the access mode, and --account-settings adds userdetails:*:rw for password, email, and 2FA-enrolment changes — rwa alone does not grant those. An api-key update replaces the key's entire scope set, so run fastio auth api-key get <key-id> first and re-state every scope it should keep. If those scopes do not all use the same access mode, re-state them with the raw --scopes '[...]' form: --admin and --read-only apply to every entity in the request, so neither can express a mixed set. A blanket --admin escalates a read-only scope to admin along with the one you meant to raise; a blanket --read-only downgrades a writable or admin scope along with the one you meant to narrow. fastio auth oauth narrow <session-id> gives up authority on a login session and takes effect at its next token refresh.
Service Account Keys
For automation that should not act as a person, a workspace admin or owner can create a service account — a non-human member of one workspace with a viewer or editor role — and give the job its key:
# As the admin: create the account and its first key (the secret is printed once)
fastio service-account create --workspace 1234567890123456789 --name ci-bot --role editor
# In the job: use the secret like any API key
export FASTIO_API_KEY=fio_sa_...
fastio auth status
A service account key is limited to its one workspace.
Roles: viewer (read, download, search, AI chat) or editor (viewer plus upload, edit, move, rename, trash, metadata, comments).
Management and sharing operations (members, invitations, creating shares, File Shares, sign, imports, org changes, permanently purging files or emptying the trash, key/account management) return HTTP 403 with reason service_account_not_permitted. Identity reads (auth status, auth check, workspace list) work, and public share links behave as if the request were anonymous.
The secret cannot be retrieved again; if it is lost, fastio sa key create a new one and fastio sa key revoke the old one.
Two-Factor Authentication
# Check 2FA status
fastio auth 2fa status
# Enable 2FA
fastio auth 2fa setup --channel totp
# Verify a pending 2FA code
fastio auth 2fa verify --code <CODE>
2FA during auth login is handled on the browser sign-in page, not in the CLI — these commands are
for managing your 2FA settings (enrollment, status, disabling).
Output Formats
All commands support --format to control output:
# Table format (default for terminals)
fastio org list
# Markdown format (default when piped; optimized for LLM consumers)
fastio org list | cat
# JSON format (for scripts that parse structured output)
fastio org list --format json
# CSV format
fastio org list --format csv
# Explicit markdown (GitHub-flavored, byte-equivalent to the server's ?output=markdown)
fastio org list --format markdown
# `--format md` is accepted as an alias
# Filter specific fields
fastio org list --fields name,id,description
Markdown replaced JSON as the non-TTY default on 2026-04-15. The
rendered output is byte-equivalent to what the Fastio API produces
for ?output=markdown: a **Result:** success|failure preamble,
object-valued errors promoted to a leading # Error section, and each
remaining top-level key as an H1 section in insertion order. Arrays of
associative records render as GFM pipe tables (union of keys in
insertion order); scalar lists render as bulleted lists.
Note on escaping: bullet values and heading text are not escaped —
the renderer takes a light-touch approach matching the server contract,
because the output is meant to be read or rendered, not embedded into
other markdown. Downstream consumers that render the output to HTML
MUST sanitize. The renderer does strip Unicode bidi, zero-width, and
C0/C1 control characters as a Trojan-Source defense; table cells escape
|, \, `, and newlines; HTML-like cell content is wrapped in
inline-code fences.
Pipelines that need machine-parseable output can opt back in with
--format json.
Commands
Authentication & User
Organizations & Workspaces
Files & Storage
Shares & Collaboration
AI
Platform
Utilities
MCP Server Mode
The CLI includes a built-in Model Context Protocol server for AI agent integration. Run it as a subprocess:
fastio mcp
This exposes the CLI's action-routed tool surface as MCP tools over stdio, compatible with Claude Desktop, VS Code, and other MCP-compatible clients. A few high-risk or local-byte operations (sign send/void, fileshare upload write-back and ws-token, and service account management, which mints secrets) remain CLI-only.
Tool responses are rendered as GitHub-flavored Markdown by default,
byte-equivalent to the Fastio API's ?output=markdown output.
Markdown is substantially more token-efficient for LLMs than
pretty-printed JSON, so the MCP server uses it for every read and
status response.
{
"mcpServers": {
"fastio": {
"command": "fastio",
"args": ["mcp"]
}
}
}
Filter which tools are available:
fastio mcp --tools auth,org,workspace,files,upload,download
Authentication and backend follow the standard CLI rules: the server honors the
global --api-base, --token, and --profile flags (and the FASTIO_TOKEN /
FASTIO_API_KEY env vars), so you can point it at a non-default backend or
profile — e.g. fastio --profile staging mcp or
fastio --api-base https://api.example/current mcp.
Shell Completions
Generate shell completions for your shell:
# Bash
fastio completions bash > ~/.bash_completion.d/fastio
# Zsh
fastio completions zsh > ~/.zfunc/_fastio
# Fish
fastio completions fish > ~/.config/fish/completions/fastio.fish
# PowerShell
fastio completions powershell > _fastio.ps1
Profiles
Manage multiple accounts with named profiles:
# Set up a profile interactively
fastio configure init
# Log in to a specific profile
fastio auth login --profile work
# Use a profile for a command
fastio org list --profile work
# Set default profile
fastio configure set-default work
# List all profiles
fastio configure list
Global Options
Configuration
Configuration files are stored in the platform config directory, under a fastio-cli folder: $XDG_CONFIG_HOME/fastio-cli (typically ~/.config/fastio-cli) on Linux, ~/Library/Application Support/fastio-cli on macOS, and %APPDATA%\fastio-cli on Windows:
License
Apache License 2.0. See LICENSE for details.
