Skip to content

getting-started.md

Latest commit

 

History

History
240 lines (154 loc) · 9.3 KB

getting-started.md

File metadata and controls

240 lines (154 loc) · 9.3 KB
Raw

Getting started with finclaw

Documentation index (all topics, EN + 中文): docs/README.md

This guide is for end users installing from GitHub Releases. CLI documentation in this repository, plus finclaw --help on your machine, is the authoritative surface for the command-line tool. Deeper topics (policies, profiles, skills) live in the linked guides in this repo.

Chinese version: getting-started.zh.md

1. Install the binary

One-liner (recommended)

curl -fsSL "https://raw.githubusercontent.com/finogeeks/finclaw-cli/main/install.sh?$(date +%s)" | sh

The ?$(date +%s) query avoids stale CDN cache for install.sh. You can omit it; if the script behaves oddly, retry with the query.

Pin a version:

curl -fsSL https://raw.githubusercontent.com/finogeeks/finclaw-cli/main/install.sh | sh -s -- --version 0.1.0

Environment variables (see install.sh --help):

  • FINCLAW_VERSION — version without or with v prefix
  • FINCLAW_INSTALL_DIR — default $HOME/.local/bin

After install, ensure the install dir is on PATH (e.g. $HOME/.local/bin):

finclaw --version

Manual download

  1. Open Releases, pick a tag (e.g. v0.1.0-rc).
  2. Download one archive for your platform (see the table in README.md) and SHA256SUMS.

Checksum note: SHA256SUMS lists all platform archives. You only have one file on disk, so do not run shasum -a 256 -c SHA256SUMS on the full file (it will try to verify missing siblings). Instead verify the single file you downloaded, for example:

VER=0.1.0-rc
FILE="finclaw-v${VER}-aarch64-apple-darwin.tar.zst"   # adjust triple to your platform
grep -F "$FILE" SHA256SUMS | shasum -a 256 -c -

Or compute the hash of FILE and compare the hex digest to the first field on the matching line in SHA256SUMS.

2. First-time layout: init

finclaw init

This creates the default profile layout under your Finclaw home (usually ~/.finclaw) and a valid config.yaml with the mock LLM provider so the CLI is safe to run before you add real API keys.

If stdin is interactive, finclaw init prompts for template and related choices. Typical non-interactive patterns:

finclaw init --non-interactive                    # CI: seeds coder-style defaults unless you steer with flags
finclaw init --non-interactive --template researcher --tool-bundle basic
finclaw init --non-interactive --no-template   # scaffold config only; skip profile.yaml / IDENTITY seeding

See finclaw init --help for --force, template names (general, coder, researcher), and tool_bundle values (basic, standard, workspace, full).

Optional: reshape profile.yaml with setup agent-profile

Once the tree exists, you can reseed the on-disk agent profile from built-in templates without editing YAML by hand:

finclaw setup agent-profile

Non-interactive flags include --seed-profile-template, --seed-profile-tool-bundle, --seed-profile-force, and --seed-profile-no-template — see finclaw setup agent-profile --help. The guided LLM wizard is still finclaw setup or explicit finclaw setup llm.

3. Point finclaw at a real LLM (optional but usual)

The embedded mock provider is for smoke tests. For real models you set provider, model, and API key (or base URL for compatible endpoints).

Recommended path — finclaw setup

finclaw setup

This guides you through:

  • picking a provider (openai, anthropic, deepseek, openrouter, ollama, lmstudio, or a custom OpenAI-compatible endpoint)
  • choosing a default model
  • optionally storing an API key in config.yaml
  • setting a local/custom base_url when needed

For scripts and CI, you can skip prompts:

finclaw setup --non-interactive --provider openai --model gpt-4o-mini

Option A — finclaw config (writes YAML on disk)

finclaw config path                    # where config.yaml lives
finclaw config set llm.provider openai
finclaw config set llm.model gpt-4.1
finclaw config set llm.api_key sk-...  # or use env for the key (see below)

Option B — environment variables

Variable Maps to
FINCLAW_LLM_PROVIDER or LLM_PROVIDER llm.provider
FINCLAW_LLM_MODEL or LLM_MODEL llm.model
FINCLAW_LLM_BASE_URL or LLM_BASE_URL llm.base_url
FINCLAW_LLM_API_KEY llm.api_key
OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, LLM_API_KEY used as llm.api_key if FINCLAW_LLM_API_KEY is unset

Precedence (highest first): shell env → dotenv from .env files → config.yaml → built-in defaults.

Option C — .env files (layered)

  1. Current working directory: ./.env (only if your shell’s cwd is that directory when you start finclaw)
  2. Profile root: <profile_root>/.env
  3. Finclaw home: ~/.finclaw/.env (or $FINCLAW_HOME/.env)

For keys that should load regardless of cwd, use ~/.finclaw/.env or the profile’s .env, not only a file inside a random git clone.

Check configuration

finclaw config show
finclaw config check
finclaw doctor

doctor and config check surface missing keys, bad paths, and provider issues.

Suggested first-run loop:

finclaw init
finclaw setup
finclaw doctor
finclaw chat -m "Hello from finclaw"

Claw HTTP/API behavior depends on your deployment; day-to-day CLI flags are in finclaw --help.

4. Talk to the agent

Interactive REPL (multiline, slash commands, good for exploration):

finclaw chat

Full-screen TUI (experimental; same agent as line chat, ratatui UI — needs a TTY; ignored with -m):

finclaw chat --tui

Supervised tool approvals that need a stdin prompt may auto-reject in --tui; prefer line chat for approval-heavy sessions — see security-and-policies.md. Details: chat-and-operations.md.

One shot (script / CI, exits after the reply):

finclaw chat -m "Hello from finclaw"

Policy & approvals: published binaries run as a normal process by default. Use profile policies and supervised prompts (or ACP in the IDE) to gate destructive tools. See security-and-policies.md and acp.md.

Scripted user id: pass --user <id> or set FINCLAW_USER_ID so multi-account tests attribute turns consistently; when empty, finclaw normally derives from your OS username.

Per-session tool governance hints: --auto-approve-all-tools and --confirm-all-tools adjust how guarded tools behave for one invocation — mutually exclusive; see security-and-policies.md and finclaw chat --help.

Long-lived process (when you want a daemon on the machine):

finclaw serve

That boots the active profile. For a profile-less supervisor that starts workers on demand (finclaw serve --lazy), see chat-and-operations.md.

Use finclaw model / finclaw model <id> to change the model id when your provider supports it. Interactive finclaw model (no id, TTY) uses the same catalog picker as finclaw setup; have llm.provider set in config or pass --provider for that flow. Print the bundled catalogue without mutating config: finclaw model --list (--json).

CLI language: pass --locale en or --locale zh once on any command when you want help text or shared prompts in that language regardless of shell locale.

5. Where things live (high level)

Location Role
~/.finclaw (or FINCLAW_HOME) Default data root
~/.finclaw/profiles/<name>/ Per-profile config, skills, policy, etc.
finclaw config path Active config.yaml for the current profile

Use finclaw profile --help for copy/backup flows.

Skills: configure hubs with finclaw skills list / check / hubs / install, or drop packs into ~/.finclaw/profiles/<name>/skills/<id>/. Use finclaw skills --help for all flags.

6. What to explore next

Goal Guide
Use finclaw inside Zed (ACP) acp.md
Let the agent learn memory & skills after turns learning.md · finclaw learning status
Talk to other agents (A2A) a2a.md
Tighten policies / approvals security-and-policies.md

7. Updates

New builds appear on Releases. Re-run the one-liner or download the new archive, re-verify checksums, and replace the binary. The finclaw update command documents the channel; behavior depends on your edition—read the on-screen help.

8. Problems?

  • Install / download / checksum / extract: open an issue with the release tag, file name, and OS + CPU (e.g. macOS 15, arm64).
  • Product / agent behavior (private deployments): use your org’s support channel if applicable; this repo focuses on shipping and installing the public binary.

Overview and links: root README.md · full index docs/README.md