This page describes the first version of the package. For version 0.3, with every studio, API keys and price approval, see the new setup guide.
The yesilcam-studios npm package gives you two commands. yesilcam is the command-line interface: everything you click in the app, you can run from a shell, with JSON output for the next tool in the chain. yesilcam-mcp is a Model Context Protocol server that lets Claude operate the studios as tools. Both use your normal account and your normal credit wallet, so a script and a colleague in the app never collide: they share the same queue and the same balance. This guide covers installation, sign-in, the main commands, the MCP setup and the habits that keep automation safe.
Install and sign in
- Install globally:
npm install -g yesilcam-studios. - Sign in once:
yesilcam login. It asks for your account credentials and stores an access token. - Check it worked:
yesilcam balanceprints your credit balance.
The token is saved to ~/.config/yesilcam/config.json with owner-only file permissions. Run yesilcam logout to remove it, for example before handing over a machine. The token grants full access to the account, including spending credits, so treat it like a password: do not commit it, do not paste it into shared chats, and replace it by logging out and in again if it may have leaked.
Generate from the terminal
yesilcam image "a lighthouse at dusk, 35mm film" --tier standard --out lighthouse.pngcreates an image on the standard tier and saves it.yesilcam video --from 1234 --duration 5 --waitstarts a five-second clip from image 1234 and waits for it to finish.yesilcam tryon --garment 88 --person 77 --out look.pngruns a try-on with a garment asset and a model.yesilcam maket analyze plan.dxfreads a floor plan and reports walls, doors, windows and rooms.yesilcam maket create "Villa",yesilcam maket save ground.dxf --project 12 --floor 0andyesilcam maket plans 12mirror the project and plan model in the app.
Add --json to any command for machine-readable output; the ids it returns are what you feed to the next command. --wait blocks until the job finishes instead of returning at once with a job id. Every job costs exactly what it would cost in the app, with your plan multiplier applied, and failed jobs are refunded the same way.
Scripting patterns
- A nightly catalog. Loop over a folder of garment photos: upload each with
yesilcam --json assets upload, read the asset id, then runyesilcam --json tryonwith--waitand--out. Forty garments become forty looks while you sleep. - Storyboards from a script. Split a screenplay into scene prompts and loop
yesilcam imageon the draft tier into a folder. Review the folder, then rerun only the keepers on standard. - Plan checks in CI.
yesilcam maket analyze plan.dxf --jsonreturns the detected walls, doors, windows and rooms. Fail the build if a plan has no rooms or its units had to be guessed.
One rule: run jobs one after another rather than in parallel when you need their ids in order. Parallel runs are fine for independent work, but a script that assumes job 2 was created after job 1 must submit them sequentially.
Connect Claude
The MCP server exposes the studios as tools: create image and video, run a try-on, check job status, list library assets, list characters, read the balance, quote prices, and analyze or save Maket plans. Setup takes two commands.
- Print your token:
yesilcam login --jsonand copy thetokenfield. - Register the server with Claude Code:
claude mcp add yesilcam -e YESILCAM_TOKEN=<token> -- yesilcam-mcp.
Claude Desktop reads the same server from its configuration file; yesilcam mcp prints the snippet to paste there. Once connected, you describe the outcome and Claude sequences the calls: "Storyboard these six scenes on draft, show me the frames, then produce the two I pick on standard." It creates the jobs, waits, returns the URLs, and, because the pricing tool is available, can quote a cost before committing.
Keeping a human in the loop
Draft work can be autonomous. Standard and cinema production should wait for your explicit yes, because that is where the credits go. Say so in your instructions ("ask before any job above draft") and Claude will ask. The same applies to scripts: put the tier in a variable, default it to draft, and make the higher tiers an explicit flag. Check the balance before a long batch, and remember that the wallet is shared with the app, so a colleague producing a film at the same time draws from the same credits.
Troubleshooting
- Command not found. The directory where npm puts global binaries is not on your PATH. Add it and open a new shell.
- Unauthorised. The stored token was removed, or the config file was deleted. Run
yesilcam loginagain. - The MCP server does not appear. The environment variable name is
YESILCAM_TOKENand the value is the token fromyesilcam login --json, not your password. Restart the client after adding the server. - A job returns no output. Check its status; a failed job is refunded and can be resubmitted.
Frequently asked
Does the CLI cost extra? No. It uses the same credit wallet and the same prices as the app.
Where is the token stored? In ~/.config/yesilcam/config.json, readable only by your user. yesilcam logout deletes it.
Can Claude spend credits without asking? Only if you let it. Every tool reports the job and its status, the pricing tool lets it quote first, and an instruction to ask before non-draft tiers is respected.
Can I use the CLI and the app at the same time? Yes. Jobs from both appear in the same queue and the same Library.
