arg CLI is a single Go binary that wraps the arg.ai REST API. It stores your token in the OS keychain, browses and searches workspace files, uploads and downloads (with multipart + resume), starts a workspace-aware terminal agent, installs agent skills, and mounts a workspace into a local coding harness like Claude Code or Codex.
It’s the lowest-friction surface for anything that lives in a terminal — Bash scripts, CI jobs, cron, and ad-hoc file moves. For when to reach for the CLI versus MCP or the REST API, see the comparison.
Install
macOS and Linux — one line:~/.local/bin (override with ARG_BIN_DIR) and verifies the download against the release’s minisign-signed checksums before installing. Update it in place later with arg update.
Homebrew and npm are coming soon. Once published:
brew install relevanceai/tap/arg or npm install --global @arg-ai/cli. Binary downloads for macOS, Linux, and Windows are also attached to
each GitHub release — useful for Windows
or air-gapped environments.Sign in
arg login performs Dynamic Client Registration, opens your browser, and stores the resulting access_token + refresh_token in your OS keychain (macOS Keychain, Linux libsecret, Windows Credential Manager). Tokens refresh automatically when a request returns 401. --timeout (default 5m) caps how long it waits for the browser callback.
Pick an org and workspace
Most commands act on an active org and active workspace, saved to your config so you set them once.workspace is aliased to ws. create takes --visibility <org|private|restricted> (default org) and --region <enam|wnam|weur|eeur|apac|oc> (default: your organization’s storage region). Any file command also takes --workspace <id-or-name> to override the active one for a single invocation. The interactive picker in arg mount and arg agent --mount includes Create workspace after a separator, and asks for those settings instead of taking flags. It saves the completed org/workspace selection, including a newly created workspace, so the next picker starts on the same pair.
Work with files
These mirror the POSIX tools you already know, but run against a workspace.arg ls [path]
arg ls [path]
List files and folders.
-l/--long shows type, size, and modified time; -R/--recursive walks the subtree (cheap — one tree call); --depth <n> caps a recursive walk.arg cat <path>...
arg cat <path>...
Print one or more files to stdout.
-n/--number prefixes line numbers across all inputs. Binary files are refused on a TTY unless you pass --binary and pipe the output.arg grep <pattern> [path]
arg grep <pattern> [path]
Client-side regex search over file contents.
-i ignore case, -l list matching paths only, -c per-file counts, --include <glob> restricts by filename, --max-results <n> caps total matches (default 1000), --concurrency <n> tunes parallel fetches. Exits 1 when nothing matches.Upload and download
arg upload returns a full, openable Arg URL for every successful file (summary.uploaded[].url with --json, or the URL column in human-readable output). It switches to multipart automatically above 32 MiB and resumes interrupted uploads from a local cache (--resume), so it’s safe to re-run. Useful flags: --concurrency / --file-concurrency, --chunk-size, --keep-going (continue past per-file failures), and --dry-run.
arg download auto-detects file vs folder, writes atomically (temp file → rename) so an interrupted download never leaves a half-written file, and guards folder zips against path traversal. Use --force to overwrite, --no-clobber to skip existing files, and --stdout to pipe a single file.
Publish a template
Publish one or more local files directly to the template catalog. The CLI creates the ZIP payload and prints the listing URL.--type accepts workspace, folder, file, skill, or subagent and defaults to workspace. A single directory contributes its contents at the template root; multiple inputs keep their basenames. File, skill, and subagent templates take one regular file. Skill and subagent sources are placed into their required .skills/<name>/SKILL.md and .agents/<name>.md paths automatically.
You do not need a source workspace or a selected workspace to publish local files. Publishing a folder with --type workspace creates a workspace template with the same clone behavior as publishing an existing workspace: its files become the new workspace’s root contents. Local templates have no workspace source to sync from, so publish again when their files change.
Use --generate-thumbnail to render the template’s entry file - its app launcher, its README, or the first file you chose - into catalog media during publish, or --thumbnail <path> to upload an image or short video. These options are mutually exclusive, and catalog media is never copied when the template is cloned. A template with motion (a .video, or a .design with video or shader fills) gets a short muted video as its automatic thumbnail; add --thumbnail-still to capture a PNG instead. A video --thumbnail is optimized before upload: if ffmpeg is installed (or ARG_FFMPEG points at it) the CLI turns it into a muted MP4 of at most 6 seconds, no larger than 1280x720 and 4 MiB, that starts playing immediately; without ffmpeg an MP4 or MOV is only rearranged to start faster. Pass --thumbnail-raw to upload the file exactly as it is. With ffmpeg, the CLI also uploads the video’s first frame as a still poster that the card shows before the video plays and if it cannot play; pass --thumbnail-poster <image> (PNG, JPEG, or WebP, up to 5 MiB) to choose that still yourself. For a multi-page template, add --thumbnail-pages p1.png,p2.png,p3.png (or --thumbnail-pages-from <dir>, which reads PNG and JPEG files in filename order - zero-pad the numbers) to upload every page as a strip that catalog cards pan across on hover. It takes 2 to 12 pages and works beside either thumbnail option. --generate-thumbnail captures a strip by itself for a multi-page design. Archives are limited to 25 MiB compressed, 50 MiB expanded, and 1,000 files. Use --org <id> to override the active organization.
Publish an existing workspace with arg templates publish --workspace <id-or-name> --title "Starter". Add --type folder|file|skill|subagent and --source-path <path> to select its source, and --thumbnail-source-path <path> for workspace catalog media. Workspace publishing takes its organization from the source; an explicit --org must match. Local paths and workspace source flags cannot be mixed.
All publish-modal settings are available: --type, --title, --description, --category, repeatable --tag, --visibility public|unlisted|org|private, --allow-preview (off by default), and automatic/custom/no thumbnail (omit both thumbnail flags for none). The CLI also supports --icon and --slug.
Publishing uses the account from arg login unless --api-key or ARG_API_KEY selects an API-key principal. --org selects the organization, never a different publisher; arg whoami shows the current identity, and JSON publish output includes owner_user_id and owner_org_id. The server checks membership, source write access, and publishing permissions before creating a snapshot.
Local directory uploads skip dot-prefixed entries except root .skills, .agents, and .well-known, plus dependencies, cache/scratch files and root .gitignore matches. Explicit file inputs are included as requested; symlinks are rejected. Choose source files intended for distribution. Publishing does not automatically retry network/server failures because the original request might have completed; check the catalog before retrying manually.
Correct a published template
Change the catalog listing of a template that is already published.--title, --description, --icon, --category, and repeatable --tag. Only the flags you pass are changed - everything else keeps what is stored - and an empty value clears a field (--description "", or --tag "" to remove every tag).
This edits the listing only. The published files and their version history are untouched, no new version is created, and the slug never changes, since it is the template’s permalink. Use arg templates publish to publish new bytes. A slug is resolved against the templates you published; pass the template id to edit one your organization owns but you did not publish.
Chat with a workspace agent
arg agent opens an interactive terminal chat against the active workspace. It connects to the workspace MCP server first, then preloads its guidance, the live bundled and workspace skill catalog, and root CLAUDE.md or AGENTS.md instructions before chat starts. File reads, writes, searches, sandbox commands, actions, sites, comments, and skill loading run through the same authenticated workspace MCP tools as hosted Arg chat.
The bundled Arg skills are loaded as a native Pi package from the public arg-ai/agent-plugins GitHub repository. Workspace skills are loaded through MCP into a private temporary skill directory. Type /skill: to see both sources in Pi’s slash completion, for example /skill:arg-files or /skill:prs.
Its startup header shows the authenticated user, active organization, selected workspace, and local-tool mode.
The context is assembled through the existing MCP connection, so there is no separate agent-context API rollout to coordinate. Missing root instruction files are fine. Authentication, workspace access, and MCP connection errors still stop the command.
--pi-arg, for example --pi-arg=--continue; Arg removes any option that could replace the workspace prompt, tools, sessions, or resources.
Local file and shell tools are disabled by default. Pass --yolo to enable unrestricted local tools, starting in the current directory, while keeping the selected Arg workspace connected. This mode is not OS-sandboxed and runs with your normal user permissions. Local extensions, ambient skills, prompts, and context discovery remain disabled.
arg agent needs Node.js 22.19.0+, npm, GitHub access for the public Arg skill package, and workspace API access. The first run downloads the pinned Pi and MCP SDK packages into npm’s cache; Pi also caches the public Git skill package and refreshes it on later runs. The arg binary remains standalone for every other command. The command is interactive, so JSON output flags do not apply.
Launch your local agent CLI
If you already use Claude Code, Codex, Pi, Hermes Agent, or OpenClaw,arg claude, arg codex, arg pi, arg hermes, and arg claw start your own installed harness and make sure it can reach Arg. The harness runs in the directory you are already in - your repo - so this gives your normal local setup access to an Arg workspace without mounting one.
Before the harness starts, the CLI prepares current Arg skills and an arg MCP server in a private temporary directory. It passes that directory to the harness only for the child process, then removes it after exit. It does not install skills, edit your project, or change the harness’s persistent configuration. Because nothing is installed, this launch flow does not need an install-location picker.
Add --arg-system-prompt to opt this child session into a short description of arg.ai and guidance to use Arg for artifacts and internal apps. The text is appended to the harness’s built-in instructions, is absent by default, and disappears when the harness exits.
This is not mounting.
arg mount -- claude makes the
workspace your agent’s working directory and syncs edits both ways. The launch wrappers mount
nothing and sync nothing - they leave you in your own repo and just wire the harness up to Arg.--arg-, so they can never clash with one of your harness’s flags. Put them first: parsing stops at the first argument Arg does not recognise, and a bare -- ends it too.
--arg-workspace <id-or-name>- the workspace the MCP server points at. Defaults to your active workspace.--arg-org[=<id-or-slug>]- register an org-scoped server instead, so the harness can pick a workspace itself. Bare--arg-orguses your active org; a value needs the equals form. Can’t be combined with--arg-workspace.--arg-no-sync- skip the temporary integration and launch straight away.--arg-sync-only- validate the temporary integration and exit without launching.--arg-system-prompt- append the Arg product context for this child session. It cannot be combined with--arg-no-sync.-h,--help, or--arg-help- print the Arg wrapper help and exit. Usearg <harness> -- --helpfor the harness’s native help.
--json, --quiet, and friends) don’t apply here.
If session preparation fails, the CLI prints a warning and your harness still starts, so a hiccup never locks you out of your own tools. The exception is --arg-sync-only, where validation is the whole job and a failure is an error. If you have no workspace selected, Arg uses the active organization instead; with neither selected, it loads the temporary skills, warns, and launches without MCP.
Mount a workspace into a coding agent
arg mount is the headline workflow: it mounts a workspace into a local directory, launches a coding harness against it, and syncs file changes both ways until the harness exits — then cleans up.
-- is passed to the harness untouched (arg mount -w ws -- claude --model opus). Other flags: --dir (mount base, default .arg), --poll (sync interval, default 3s), --api-key (or ARG_API_KEY — authenticate without a browser, ideal for CI), --no-cleanup, and --ignore-file (gitignore-style, default .argignore).
After you choose an org or workspace in the picker, the CLI remembers the resolved pair as your active selection. Choose Create workspace at the bottom of the workspace menu to set up and select a new workspace without leaving the flow - it asks for a name, who can reach it, and (when your organization allows a choice) where its files are stored. The next picker highlights the active pair, and other commands use it automatically. A fully explicit invocation that shows no picker applies only to that invocation.
--arg-skills copies the Arg plugin skills from the root skills/ directory, or from the release binary’s embedded snapshot generated from it, into only the layout for the detected harness. Claude Code gets .claude/skills/, Codex gets .agents/skills/, Pi gets .pi/skills/, and OpenClaw gets workspace-level skills/. Hermes gets a temporary child-process HOME whose .hermes/skills contains the Arg skills while the real ~/.hermes config and existing skills are overlaid by symlink. Existing files are skipped, and the preload is treated as local baseline state so the files are not uploaded just because the flag was used. Set ARG_SKILLS_SOURCE_DIR to point at a specific local skills directory.
Lazy mode (--mode fuse). By default (--mode watch) the workspace is downloaded and kept in two-way sync. With --mode fuse nothing downloads up front — the folder tree appears instantly and each file’s bytes are fetched the first time your agent reads it (edits upload on save). Great for huge workspaces where the agent only touches part of the tree. It needs a FUSE provider — on macOS install FUSE-T with brew install macos-fuse-t/homebrew-cask/fuse-t (no kernel extension, no sudo to mount) — and a FUSE-enabled CLI build; the standard binary will tell you how to get one. Note a coding agent that scans the whole repo will fetch most files anyway, so watch (with its cache) is usually faster — reach for fuse when the workspace is large and your task is narrow.
Mounts are fast on repeat: file contents are kept in a central content cache (~/.cache/arg/mount/, keyed on each file’s server change stamp), so re-mounting an unchanged workspace transfers no bytes — files are restored from the local cache (a copy-on-write clone where the filesystem supports it). Only changed and new files are downloaded, and they warm the cache for next time. Pass --no-cache (or ARG_NO_CACHE=1) to always download fresh; tune the cache with ARG_CACHE_DIR and ARG_CACHE_MAX_BYTES (default 5 GiB before least-recently-used eviction).
The workspace becomes your agent’s shared, durable memory: it reads and writes the same files a
teammate sees in the arg.ai UI, and anything it produces is queryable over the REST
API the moment it lands. See the agent-loop
recipe.
Install agent skills
The CLI reads reusable agent skills directly or installs them into.claude/skills/ (or .agents/skills/ if that directory exists), verifying each file’s SHA-256. Current CLI builds include the default arg.ai skill registry in the binary; set ARG_SKILLS_REGISTRY only when testing a custom registry mirror. Registry overrides can use the legacy arg registry shape or a well-known Agent Skills discovery v0.2.0 skill-md index. The same bundled skills are discoverable at https://arg.ai/.well-known/agent-skills/index.json.
skills get verifies the same SHA-256 digests as installation but keeps the result in memory and writes no skill directory. Its default output is the exact SKILL.md; pass a listed relative path for one support file, --json for a content envelope, or --full for every file in one JSON document. Full output marks each member as utf-8 or base64, so binary resources remain lossless. Individual in-memory files are limited to 16 MiB and full bundles to 64 MiB.
Installs are atomic: files stage to a temp dir, verify, then swap into place, so a failed download never corrupts an existing skill. Pass --force to reinstall.
Render editor files headlessly
Export a.design, .psd, .daw, or .video document to an image, audio, or video file straight from the terminal - no editor UI and no signed-in app session. It’s built for CI jobs, cron, and scripts that turn workspace documents into deliverables.
Provision the renderer once
Rendering needs a headless browser and ffmpeg. Provision them once with any kind’s install command - one install serves every renderer.Render a document
Each editor has a focused command that exposes its own formats and options. The top-levelarg render <path> picks the renderer from the file extension.
Input paths
The path can be a local file, a bare workspace path, or anarg:// deep link or arg.ai URL.
-w/--workspace to override the active workspace.
Dynamic designs and videos
The renderer runs standalone, without a signed-in Arg session, so it can’t pull live data on its own. Treat each render as a point-in-time snapshot: fetch the data yourself, write it into the document, then render. Give every field that automation replaces a unique, stable name in the editor - select the layer or clip and rename it. Object and clip ids are generated and can’t be set, so the name is the handle your script matches on. Then fetch, materialize, upload, and render. This example expectsDATA_URL to return { "headline": "...", "value": 123 }:
.design stores objects in a map keyed by their generated id, so with_entries updates only the objects whose name matches and never adds a new one. A .video timeline stores clips in an array, so select them by name instead:
Built-in
.video stock and weather clips fetch live data through the app, which the standalone
renderer can’t reach, so they render an error card. Bake those values into text or a static image
before a headless render.Send a notification
arg notify sends a notification that opens a specific Arg file, folder, chat, or Action run. The last argument is the Arg URL. Recipients before it can be me, a user id, or an email address in one of your organizations. Omit recipients to notify yourself.
--channel to narrow delivery to ios, email, and/or in-app; each recipient’s preferences still apply. Use --title to override the title inferred from the target and --body for extra context.
Configuration
arg config get|set|list|path manages persistent settings, stored as plaintext YAML you can version-control (tokens live in the keychain, never here).
Precedence, highest first: command-line flag →
ARG_* env var (ARG_API_URL, ARG_ACTIVE_ORG, ARG_WORKSPACE, ARG_OUTPUT_FORMAT, …) → config file → built-in default. The file lives at $XDG_CONFIG_HOME/arg/config.yaml (~/.config/arg/config.yaml by default).
Output and scripting
Every command is pipe-friendly and built for both humans and scripts.- Stdout is data. A table on a TTY, JSON when piped or when you pass
--json. - Stderr is for humans: progress, warnings, errors.
NO_COLOR=1or--no-colorsuppresses ANSI;--quietdrops progress;-v/-vvadds detail.
Updating
arg update reads signed artifacts from relevanceai/arg-releases, verifies checksums.txt.minisig with the public key embedded in the binary, then verifies and swaps the binary. Homebrew and npm installs are detected and left untouched (brew upgrade arg / npm install --global @arg-ai/cli@latest).
Standalone builds check for updates once a day on successful interactive commands — skipped in CI, JSON mode, quiet mode, and pipes. Disable with ARG_NO_UPDATE_CHECK=1 or arg config set update_check false.
Related
- Recipes & patterns — local-to-cloud workflows built on the CLI
- Sync a local folder — one-shot and continuous mirroring
- API keys — credentials for headless
--api-keyuse - MCP guide — the same workspace as a live agent tool surface