Skip to main content

Site Administration

The CLI App lets administrators inspect and configure their Files.com site from a terminal, a script, or an AI agent. Use it to repeat account setup, maintain group membership and access, configure connected storage and workflows, or investigate the current state of a site. The same commands support an individual change and a process that applies an intended configuration across many resources.

Administration often involves related resources rather than a single setting. Giving someone access can involve a user, a group, a membership, and folder permissions. Configuring connected storage can involve a Remote Server and the folder setting that mounts it. Understanding those relationships lets you choose the records to inspect and change.

Account and Workspace Scope

Choose the intended authentication and profile before inspecting or changing a site. Use the same named profile throughout the task so that IDs you retrieve and commands you run refer to the same account.

Commands use the permissions of the configured user or API key. An AI agent operates with those credentials' authority. An API key with the Files Only scope cannot perform administration. A key's path restriction limits direct file operations, rather than its administrative capabilities; choose its user and permission scope for the administration it needs to perform.

For sites using Workspaces, set --workspace-id when the task concerns a particular Workspace. Selecting a Workspace scopes the command; it does not grant access to that Workspace.

Resources and Command Discovery

Start with the installed CLI's command descriptions and workflow guides. You can discover them without credentials or a network connection:

files-cli commands search group
files-cli commands describe group-users create --format=json
files-cli workflows show filescom-groups

commands describe identifies the command's arguments and flags. workflows provides bundled guides for working with resources and completing tasks. You can also use --help on any resource or action, and consult the CLI referenceExternal LinkThis link leads to an external website and will open in a new tab for command documentation.

Find the ID of a record by listing its resource. Keep related IDs distinct: a user ID identifies an account, while a group membership joins that user to a group. Folder Settings use the behaviors commands, so updating a Remote Server Mount requires its folder setting ID; the Remote Server ID identifies the connected storage.

Changes and Verification

Read the current state before applying a change, including the relationships that determine the result. After the command completes, retrieve the affected record or relationship to confirm it matches the intended configuration. For repeated work, compare the existing state with the desired state so that running the process again does not create duplicate resources or repeat completed changes.

For example, adding an existing user to a Group managed directly in Files.com creates a membership between two existing records. The Group's folder permissions apply to its members, so review the access the Group provides before adding someone. Groups managed by an identity provider follow that provider's provisioning controls.

With a profile named operations already configured, identify the user and Group:

files-cli users list --filter=username=amy --fields=id,username --profile=operations --format=json
files-cli groups list --filter="name=Delivery Team" --fields=id,name --profile=operations --format=json

Use the returned IDs in subsequent commands. If the Group ID is 1111, inspect its current memberships:

files-cli group-users list --group-id=1111 --profile=operations --format=json

If the intended user's membership is absent, add it. This example uses user ID 12345; replace both IDs with the values you retrieved:

files-cli group-users create --group-id=1111 --user-id=12345 --profile=operations --format=json

List the Group's memberships again and confirm that the returned records contain the intended user and Group IDs. This verifies the membership change. The user's effective access also depends on the Group's permissions and any other permissions that apply to the user.

AI Agents and Unattended Scripts

Give an agent the intended site, Workspace, task, and scope of changes. It can use the CLI's command descriptions to discover the available operations and its bundled workflows to understand how related resources fit together. The agent contextExternal LinkThis link leads to an external website and will open in a new tab documents the invocation contract, and the skill indexExternal LinkThis link leads to an external website and will open in a new tab provides domain guides and recipes for agents that load skills directly.

Use --format=json for structured results and --non-interactive to prevent prompts. Configure credentials first: without a usable API key or session, a non-interactive command fails instead of asking someone to log in.

files-cli users list --fields=id,username --profile=operations --format=json --non-interactive

Check the process exit code and diagnostics before using a result or continuing with dependent changes. A failed command needs its cause addressed; JSON result formatting does not turn every failure into a JSON error response.

For large inventories, use --json-envelope on list commands that support cursor pagination. It returns a bounded page of records with continuation information:

files-cli users list --fields=id,username --profile=operations --format=json --non-interactive --json-envelope --per-page=100

Process the returned data, then pass next_cursor as --cursor on the next call while has_more is true. Keep the profile, Workspace, and filters consistent between calls. An empty filtered page can still have more records to fetch; use has_more to determine when the listing is complete.